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。

我试图在autoclass：

下添加单个automodule指令

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

   .. autoclass:: B
      :inherited-members:

   .. autoclass:: C
      :inherited-members:

这会产生意想不到的效果：放置正确记录的B和C版本，包含继承成员，然后是A，B，{的完整文档{1}}，所有文件都没有继承成员。

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

我在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：

对于类和异常，除了inherited-members之外，除非你提供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中的选项。

<强>更新

实际上可以在automodule来自同一模块的autoclass指令后，如果:exclude-members:选项中出现automodule选项，则行为正确{1}}：

.. 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不会继承任何选项，因此与原始问题中示例的唯一区别是:exclude-members:和automodule中添加的:members: autoclass。

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

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

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

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

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

2 个答案: