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

Question

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

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

__main__.py看起来是这样的：

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

if __name__ == '__main__':
    main()

我希望在sphinx生成的RST文件中包含main()、f1()和f2()。

有一个类似的问题，') using sphinx，但它没有回答我的问题。

Answer 1

我认为这是一个没有文档的特性，或者是sphinx-apidoc v.3.2.1中的一个bug。如果我们查看 option，它会读到：

-P，--私有包含“_private”模块。

注意，这里没有提到 from autodoc flag options。

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

sphinx-apidoc将根据两个主要模板( package.rst_t )生成.rst文件。(在Windows上使用狮身人面像和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文件。

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

私有类/方法/变量(模块中的对象)受autodoc option的影响。

sphinx-apidoc设置由SPHINX_APIDOC_OPTIONS环境变量(即:members:、:undoc-members:和show-inheritance)定义的生成的.. automodule::指令的默认autodoc选项。这些选项不能作为命令行参数传递，您必须在运行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文件，每个包包含每个模块一个指令。这样就没有实现这一目标的实际可能性(不诉诸大量黑客)。您最好的选择是在生成每个.. automodule::文件之后，将每个__main__.py的一个.rst指令复制到它们中。