问题描述
我无法在使用sphinx-apidoc生成RST文件时正确添加我的__main__.py文件及其函数。其他文件和类已正确生成。
仅当我使用-P参数运行sphinx-apidoc时才能工作，该参数包括私有模块。但我不想添加其他模块的私有方法，我只需要来自__main__.py的这些方法。
__main__.py如下所示：
def main():
"""
main() description here
"""
f1()
f2()
if __name__ == '__main__':
main()
我希望在sphinx-apidoc生成的RST文件中包含main()、f1()和f2()。
有一个类似的问题Documenting python script entry (__name__ == '__main__') using sphinx，但它没有回答我的问题。
推荐答案
我认为这是一个未记录功能，或者它也可能是v.3.2.1中的错误。如果我们查看documentation for -P option，则为：
-P, --private Include "_private" modules.
请注意，这里没有提到:private-members: from autodoc flag options。
合并了两个不同的问题，一个模块内的"；私有模块和"；私有对象。根据官方文档，影响.rst文件生成的选项应有所不同。
sphinx-apidoc将基于2个主模板module.rst_t and package.rst_t生成.rst文件。(在Windows上使用Sphinx和venv可在/venv/Lib/site-packages/sphinx/templates/apidoc下找到)。
.rst文件，并在该文件中为每个模块生成1个.. automodule::指令。-P选项的作用(假定)是向每个私有模块的.rst文件中再添加一个指令.. automodule:: your-package.__private-module__。
另一种方法是将-e选项与sphinx-apidoc一起使用，在这种情况下，将为每个模块和包生成一个单独的.rst文件。因此，使用sphinx-apidoc -e -P将导致为私有模块生成额外的.rst文件。
但我不想添加其他模块的私有方法
私有类/方法/变量(模块内的对象)受自动文档':private-members:' option影响。
sphinx-apidoc设置由SPHINX_APIDOC_OPTIONS环境变量定义的生成的.. automodule::指令的默认自动对接选项(即:members:、:undoc-members:和show-inheritance)。这些选项不能作为命令行参数传递，您必须在运行sphinx-apidoc更改缺省值之前设置环境变量。(与自动文档不同，sphinx-apidoc不会从conf.py获取它们。)
查看apidoc.py的源代码
# automodule options
if 'SPHINX_APIDOC_OPTIONS' in os.environ:
OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',')
else:
OPTIONS = [
'members',
'undoc-members',
# 'inherited-members', # disabled because there's a bug in sphinx
'show-inheritance',
]
因为:private-members:是默认的自动对接选项，应该使用SPHINX_APIDOC_OPTIONS设置选项(如文档状态和源代码所示)。如果包含-P选项，则其唯一(记录在案的)效果应该是为私有模块添加.. automodule::指令，实际发生的情况是，它还会在每个指令上设置:private-members:自动对接选项。
以下树：
your_package
├ one_module.py
├ __init__.py
└ __main__.py
withsphinx-apidoc -P将生成：
your_package.__main__ module
----------------------------
.. automodule:: your_package.__main__ <<-- -P option is documented as having this effect.
:members:
:undoc-members:
:show-inheritance:
:private-members: <<-- -P option is not documented to have this effect.
那么如何实现问题中所述的目标呢？
如果您使用-e选项和sphinx-apidoc为每个模块生成一个.rst文件，则可以使用签名中的[EXCLUDE_PATTERN …]。通过运行sphinx-apidoc两次，为__main__.py模块运行一次(连同-P选项)，为其余模块运行第二次。
如果您不想要模块的单独.rst文件，而是每个包的常规1.rst文件，每个模块包含一个指令。那么，实现这一目标实际上是不可能的(除非诉诸大量黑客攻击)。您的最佳选择是在生成.rst文件后，将.. automodule::指令复制粘贴到.rst文件中。
这篇关于在sphinx-apidoc生成的文件中包含__main__.py的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持编程学习网！