在自动模块指令下修改特定 class 的选项

Question

我有一个 Python 模块，my_module.py，看起来像这样：

import numpy

class A(numpy.ndarray):
    """ Extension for illustration. """
    pass

class B:
    """ My base class. """
    def x():
        """ Does the thing. """
        pass

class C(B):
    """ My extension class. """
    pass

我有一个如下所示的 reST 文件：

API Reference
=============

my_module
---------

.. automodule:: my_module
    :members:
    :special_members:

我希望能够将 :inherited-members: 选项添加到 B 和 C，但不是 A。

我试图在 automodule 下添加单独的 autoclass 指令：

.. automodule:: my_module
   :members:
   :special_members:

   .. autoclass:: B
      :inherited-members:

   .. autoclass:: C
      :inherited-members:

这会产生意想不到的效果，即放置 B 和 C 的正确记录版本以及继承的成员，然后是 A、B 的完整文档, C, 在同一个文件中都没有继承成员。

如何在不复制生成的文档的情况下为某些成员指定不同的选项？

我在 Python 3.6.2 的 Anaconda 安装上使用 Sphinx 1.6.3。

Answer 1

尝试将 :members: 添加到类 B 并将 C 和 :exclude-members: B, C 添加到模块：

.. automodule:: my_module
   :members:
   :special_members:
   :exclude-members: B, C

   .. autoclass:: B
      :inherited-members:
      :members:

   .. autoclass:: C
      :inherited-members:
      :members:

来自 automodule, autoclass, and autoexception options and advanced usage:

For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the inherited-members flag option, in addition to members:
.. autoclass:: Noodle
   :members:
   :inherited-members:

如果这不起作用，我可以完善我的答案。注释不利于提供示例代码，所以我必须使用答案。

Answer 2

基于https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example，防止文档重复的一种方法似乎是在automodule选项中添加一个显式列表:members::

.. automodule:: my_module
    :members: A
    :special_members:

   .. autoclass:: B
      :inherited-members:

   .. autoclass:: C
      :inherited-members:

这里唯一的问题是嵌套的 autoclass 元素（B、C）在模块的大部分其余部分（A）之前呈现，这不是我想要的。

解决方案是取消嵌套 autoclass 指令：

.. automodule:: my_module
    :members: A
    :special_members:

.. autoclass:: B
   :members:
   :inherited-members:

.. autoclass:: C
   :members:
   :inherited-members:

提供两个 automodule 指令，每个都有不同的选项集和不同的显式成员列表 不起作用 。结果是一条警告，指出

WARNING: Duplicate ID: "my_module".

两个 automodule 指令的选项合并在一起，使分离变得毫无意义。

在包含它的模块的 automodule 之前放置 autoclass 会导致类似的问题。 class 文档将呈现两次：一次使用 autoclass 中的选项，一次使用 automodule.

中的选项

更新

它是实际上可以将 automodule 指令放在来自同一模块的 autoclass 之后，如果 :exclude-members: 则具有正确的行为选项出现在 automodule:

.. autoclass:: my_module.A
   :members:
   :special-members:

.. automodule:: my_module
   :members: B, C
   :exclude-members: A
   :inherited-members:

如果大多数成员应该最后出现但不需要特殊处理，这很方便。

事实证明，使用 :exclude-members: 选项也适用于嵌套情况：

.. automodule:: my_module
   :members:
   :exclude-members: A
   :inherited-members:

   .. autoclass:: my_module.A
      :members:
      :special-members:

None中的选项被嵌套的automodule继承，所以与原题中例子的唯一区别是在automodule中增加了:exclude-members:和:members: 在 autoclass.

从技术上讲，这意味着也可以执行 automodule 两次：

.. automodule:: my_module
   :members:
   :exclude-members: B, C
   :special-members:

.. automodule:: my_module
   :members:
   :exclude-members: A
   :inherited-members:

但是，这个选项不是特别理想，因为它会引起警告并需要列出我们要记录的成员的逆集，这使得它不太直观。

在自动模块指令下修改特定 class 的选项

Modifying options for particular class under automodule directive

python

restructuredtext

python-sphinx

autodoc