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

问题描述

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

---

解决方案

我认为这是一个未记录功能，或者它也可能是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上使用Sphinx和venv可在/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文件。

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

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

sphinx-apidoc设置由SPHINX_APIDOC_OPTIONS环境变量定义的生成的.. automodule::指令的默认自动对接选项(即:members:、:undoc-members:和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选项，则其唯一(记录在案的)效果应该是为私有模块添加.. automodule::指令，实际发生的情况是，它还会在每个指令上设置:private-members:自动对接选项。

以下树：

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

withsphinx-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文件后，将.. automodule::指令复制粘贴到.rst文件中。