1

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

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

__main__.py 看起来像这样：

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

if __name__ == '__main__':
    main()

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

有一个类似的问题Documenting python script entry (__name__ == '__main__') using sphinx但它没有回答我的问题。

4

1 回答 1

1

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

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

请注意，这没有:private-members:从 autodoc flag options中提及。

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

sphinx-apidoc将.rst基于 2 个主要模板生成文件，module.rst_t并且package.rst_t. （在Windows上使用带有 venv 的 Sphinx，这些位于 下/venv/Lib/site-packages/sphinx/templates/apidoc）。

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

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

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

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

sphinx-apidoc设置由环境变量（即，和）.. automodule::定义的生成指令的默认自动文档选项。这些选项不能作为命令行参数传递，您必须在运行之前设置环境变量以更改默认值。（与 autodoc 不同，不会从 中获取它们。）SPHINX_APIDOC_OPTIONS:members::undoc-members:show-inheritancesphinx-apidocsphinx-apidocconf.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::为私有模块添加指令，实际发生的是它还:private-members:在每个指令上设置了 autodoc 选项。

以下树：

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为您的模块提供单独的文件，而是.rst每个包的正常 1 个文件包含每个模块的一个指令。那么就没有实现这一目标的实际可能性（不诉诸大量黑客攻击）。您最好的选择是在生成文件后简单地将.. automodule::每个指令复制粘贴__main__.py到文件中。.rst

于 2020-10-07T05:23:42.413 回答