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

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

仅当我运行 sphinx-apidoc 时我才工作-P包含私有模块的参数。但我不想添加其他模块的私有方法，我只需要 __main__.py 中的这些方法。

__main__.py 看起来像这样：

def main():
    """
    main() description here
    """
    f1()
    f2()

if __name__ == '__main__':
    main()

我想拥有main(), f1() and f2()包含在 sphinx-apidoc 生成的 RST 文件中。

有一个类似的问题使用 sphinx 记录 python 脚本条目 (__name__ == '__main__')但它没有回答我的问题。

我认为这是一个未记录的功能，或者它也可能是错误sphinx-apidocv.3.2.1。如果我们看一下的文档-P option，它写道：

-P, --private
    Include “_private” modules.

注意这没有提到:private-members:来自 autodoc 标志选项.

两个不同的问题被混为一谈，“私有模块”和“模块内的私有对象”。影响的选项.rst根据官方文档，每个文件的生成应该不同。

sphinx-apidoc将生成.rst基于 2 个主要模板的文件，module.rst_t and package.rst_t。 （使用带有 venv 的 SphinxWindows这些可以在下面找到/venv/Lib/site-packages/sphinx/templates/apidoc).

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

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

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

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

sphinx-apidoc设置生成的默认自动文档选项.. automodule::指令定义为SPHINX_APIDOC_OPTIONS环境变量（即:members:, :undoc-members: and 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',
    ]

Because :private-members:是默认的自动文档选项，应使用设置SPHINX_APIDOC_OPTIONS（如文档所述和源代码所示）。如果您包括-P选项，其唯一（记录的）效果应该是添加.. automodule::私有模块的指令，发生的情况是它还设置了 autodoc 选项:private-members:每个指令。

下面的树：

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

With 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每个包的文件，每个模块包含一个指令。那么就不可能实现这一目标（不诉诸大量的黑客攻击）。您最好的选择就是简单地复制粘贴 1.. automodule::指令每__main__.py进入.rst文件生成后。