在 sphinx-apidoc 生成的文件中包含 main.py

Question

在使用 sphinx-apidoc 生成 RST 文件时，我无法正确添加我的 __main__.py 文件及其功能。其他文件和类正确生成。

只有当我运行 sphinx-apidoc 带有 -P 参数（包括私有模块）时我才能工作。但是我不想添加其他模块的私有方法，我只需要 __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，但它没有回答我的问题。

Answer 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 文件。

But I do not want to add private methods of other modules

私有 classes/methods/variables（模块内的对象）受到 autodoc ':private-members:' option.

的影响

sphinx-apidoc 设置由 SPHINX_APIDOC_OPTIONS 环境变量（即 :members:、:undoc-members: 和show-inheritance)。这些选项不能作为命令行参数传递，您必须在运行 sphinx-apidoc 之前设置环境变量以更改默认值。（与 autodoc 不同，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: 是默认的 autodoc 选项，应该使用 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 文件。那么就没有实现这一目标的实际可能性（不诉诸大量黑客攻击）。您最好的选择是 copy-pasting 1 .. automodule:: 指令每个 __main__.py 到 .rst 文件生成后。

在 sphinx-apidoc 生成的文件中包含 main.py

Include main.py in sphinx-apidoc generated files

python

python-sphinx

autodoc

sphinx-apidoc

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

Include __main__.py in sphinx-apidoc generated files

python

python-sphinx

autodoc

sphinx-apidoc

在 sphinx-apidoc 生成的文件中包含 main.py

Include main.py in sphinx-apidoc generated files