Sphinx Autodoc 從文檔字符串中跳過成員

Question

我正在用 Sphinx 記錄一個 class 並且只是想跳過其中一個類成員：

class StatusUpdateAdapter(logging.LoggerAdapter):
    """
    """
    def __init__(self, status_update_func, logger, extra={}):
        """
        """
        pass

    def log(self, *args, **kwargs):
        pass

我怎樣才能使 sphinx 不記錄日志成員？ 如果可能的話，我想在 StatusUpdateAdapter 或日志文檔字符串中執行此操作。

Answer 1

您現在可以（從 0.6 版開始）使用:exclude-members:從文檔中排除特定成員：

支持成員文檔的指令也有一個 exclude-members 選項，如果要記錄所有成員，可用於從文檔中排除單個成員名稱。

0.6 版中的新功能。

來源： http : //www.sphinx-doc.org/en/stable/ext/autodoc.html

在您的特定情況下，您可以將:exclude-members: log到您的.rst文件中。

Answer 2

似乎沒有任何簡單的方法可以做到這一點。

作為一種解決方法，您可以在 RST 文件中嘗試類似的操作：

.. autoclass:: StatusUpdateAdapter
   :members: methodA, methodB

但這需要列出您想要手動記錄的所有方法，這可能非常費力。 如果您正在使用它，它也可能與:inherited-members:交互不佳。

另一種選擇是在您想要記錄的每個方法上放置一個文檔字符串，但在log()方法上沒有文檔字符串，然后（如有必要）使用:no-undoc-members: 。 如果您打算記錄內部接口或不記錄公共接口，這顯然不好。

最后，除非另有配置（ :private-members: ），否則 Autodoc 會跳過名稱以下划線開頭的任何內容，因此如果您使用下划線前綴的名稱，該方法將不會出現。 下划線前綴表示PEP 8 下的私有接口，它可能符合也可能不符合您的意圖。 這也可能在已建立的代碼庫中造成向后兼容性問題。

Answer 3

我不確定如何使用文檔字符串來做到這一點，但您可以使用前置下划線聲明函數/方法“受保護”。 Sphinx 不會引入該函數/方法。

def _log(self, *args, **kwargs):
     pass

Answer 4

您可以使用:meta private:以便 Sphinx 認為該方法是私有的，如果您將 Sphinx 配置為隱藏私有方法，它將被隱藏。

Answer 5

有一個類似的問題，並且考慮到（甚至）到今天似乎沒有這樣的功能，我找到了一個對我有用的解決方法選項：在 conf.py 中創建自定義autodoc-skip-member() conf.py .

這允許根據一些輸入定義何時跳過成員，包括 object 的類型、object 的名稱和 object 本身。

有關詳細信息，請參閱此問題： 將 Sphinx autodoc-skip-member 連接到我的 function ，尤其是這個答案（返回None允許 Sphinx 使用未明確排除的成員的默認行為）。

Answer 6

太晚了，但一個丑陋的解決方法是向要跳過的公共方法添加一個空的文檔字符串。 像那樣：

def log(self, *args, **kwargs):
    ""
    pass