在 sphinx-apidoc 生成的文件中包含 __main__.py答案

【问题标题】：Include __main__.py in sphinx-apidoc generated files在 sphinx-apidoc 生成的文件中包含 __main__.py
【发布时间】：2019-01-11 14:05:18
【问题描述】：

在使用 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，但它没有回答我的问题。

【问题讨论】：

sphinx-apidoc 忽略以_ 开头的文件（__init__.py 除外）。见github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/…。你需要有一个__main__.py 文件吗？可以改名吗？
@mzjn 那么你将如何自动记录模块？
创建另一个 RST 文件，在其中添加 .. automodule:: __main__。

标签： python python-sphinx autodoc sphinx-apidoc

【解决方案1】：

我认为这是一个未记录的功能，或者它也可能是 sphinx-apidoc 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 上使用带有 venv 的 Sphinx，这些可在 /venv/Lib/site-packages/sphinx/templates/apidoc 下找到。

默认行为（由模板实现）是为每个包生成 1 个 .rst 文件，并在该文件中为每个模块放置 1 个 .. automodule:: 指令。 -P 选项的作用（据说）是在每个私有模块的 .rst 文件中再添加一个指令 .. automodule:: your-package.__private-module__。

另一种方法是将-e 选项与sphinx-apidoc 一起使用，在这种情况下，将为每个模块和包生成一个单独的.rst 文件。所以使用sphinx-apidoc -e -P 会导致为私有模块生成一个额外的.rst 文件。

但我不想添加其他模块的私有方法

私有类/方法/变量（模块内的对象）受 autodoc ':private-members:' option 的影响。

sphinx-apidoc 设置生成的.. automodule:: 指令的默认自动文档选项，由SPHINX_APIDOC_OPTIONS 环境变量（即:members:、:undoc-members: 和show-inheritance）定义。这些选项不能作为命令行参数传递，您必须在运行sphinx-apidoc 之前设置环境变量以更改默认值。（sphinx-apidoc 不会从 conf.py 获取它们，这与 autodoc 不同。）

看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:: 指令，实际情况是它还在每个指令上设置了 autodoc 选项 :private-members:。

以下树：

your_package
 ├  one_module.py
 ├  __init__.py
 └  __main__.py

使用sphinx-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 文件后将每个 __main__.py 的 1 个 .. automodule:: 指令复制粘贴到它们中。

【讨论】：