修改選項

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 

我休息一下文件看起來像這樣：

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：

對於類和異常，部件從基類繼承將記錄時被排除在外所有的成員，除非你給出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指令的選項組合，使得分離毫無意義。

在automodule之前爲包含它的模塊放置autoclass會導致類似的問題。類文檔將被渲染兩次：一次使用autoclass中的選項，一次使用automodule中的選項。

UPDATE

它實際上是可能的，如果一個: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繼承，所以從例如原來的問題，唯一的區別是: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: 

此選項不是特別理想，但是，因爲它會導致一個警告，並要求反集我們想成員的清單記錄，使其不那麼直觀。