Question

使用 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，但不能回答我的问题。

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将基于两个主要模板module.rst_t and package.rst_t生成.rst文件。（在 Windows 上将Sphinx与venv一起使用可在/venv/Lib/site-packages/sphinx/templates/apidoc下找到）。

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

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

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

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

sphinx-apidoc设置生成的.. automodule::指令的默认自动文档选项，该指令由SPHINX_APIDOC_OPTIONS环境变量（即:members:，:undoc-members:和{{ 1}}）。这些选项不能作为命令行参数传递，您必须在运行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伪指令，这是因为它还在每个伪指令上设置了autodoc选项.. automodule::。

以下树：

: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文件，而是为每个包中的每个模块包含一个指令的普通1 .rst文件。这样就没有实现这一目标的实际可能性（无需借助大量黑客手段）。最好的选择是在生成文件后，将每个.rst的1个.. automodule::指令复制粘贴到__main__.py文件中。

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

1 个答案:

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

1 个答案:

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