如何在 Sphinx 中标记有条件包含的文档字符串？答案

【问题标题】：How can I tag a docstring for conditional inclusion in Sphinx?如何在 Sphinx 中标记有条件包含的文档字符串？
【发布时间】：2013-12-11 08:21:03
【问题描述】：

我的 Python 包类和方法中有大量文档字符串，它们使用 autodoc 指令引入 Sphinx 以生成项目文档。

一些外部（不以下划线开头）方法是应该出现在用户文档中的 API 方法。其他是外部的，因为它们需要从另一个模块调用，但构成一个 internal API。这些不应出现在用户文档中。

到目前为止，我已经使用 :members: 参数手动区分了用户 API 方法和内部 API 方法。当我添加新方法时，这很容易出错，我想在文档字符串中指出该方法是否应该出现在用户 API 文档中。

有没有办法我可以“标记”文档字符串或类似的东西直接出现在源代码中以指示它应该出现在用户 API 文档中？

【问题讨论】：

标签： python python-sphinx

【解决方案1】：

您似乎想从自动文档中排除成员？

.. automodule:: yourmodule
   :inherited-members:        # include inherited functions
   :special-members:          # include __functions__
   :private-members:          # include _functions and __functions
   :members:                  # include all other documented functions
   :undoc-members:            # include even undocumented functions
   :exclude-members: f_1, f_2 # exclude certain members

要更以编程方式编写条件文档，您将编辑 conf.py 文件并覆盖插槽 autodoc-skip-member，如 here 解释的那样。

def skip(app, what, name, obj, skip, options):
    return name in ["exclude1", "exclude2", "exclude3"]

def setup(app):
    app.connect("autodoc-skip-member", skip)

【讨论】：