在 automodule 指令下修改特定类的选项

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：

对于类和异常，从基类继承的成员在记录所有成员时将被忽略，除非您在members 之外提供inherited-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 指令的两个选项组合在一起，使得分离毫无意义。

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

更新

如果:exclude-members: 选项出现在automodule 中，则实际上可以在来自同一模块的autoclass 之后放置一个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:

嵌套的automodule 不会继承任何选项，因此与原始问题中示例的唯一区别是在automodule 中添加了:exclude-members: 和在autoclass 中添加了:members:。

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

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

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

然而，这个选项并不是特别理想，因为它会导致警告，并且需要列出我们想要记录的成员的反向集合，从而使其不太直观。