我的 Python 包类和方法中有大量文档字符串,它们使用 autodoc 指令引入 Sphinx 以生成项目文档。
一些外部(不以下划线开头)方法是应该出现在用户文档中的 API 方法。其他是外部的,因为它们需要从另一个模块调用,但组成了一个内部 API。这些不应出现在用户文档中。
到目前为止,我已经使用 :members: 参数手动区分用户 API 方法和内部 API 方法。事实证明这很容易出错,因为我添加了新方法,我想在文档字符串中正确指示该方法是否应该出现在用户 API 文档中。
有没有一种方法可以“标记”文档字符串或类似的东西以直接出现在源代码中以指示它应该出现在用户 API 文档中?
最佳答案
看起来你想从 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)
关于python - 如何标记文档字符串以有条件地包含在 Sphinx 中?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/20513951/