Question

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

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

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

有没有一种方法可以“标记”文档字符串或类似内容直接显示在源代码中，以表明它应该出现在用户API文档中？

Answer 1

您希望从autodoc中排除成员吗？

.. 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)

如何在Sphinx中为条件包含标记文档字符串？

1 个答案: