如何使 Sphinx autodoc 扩展包含 underscore/private Python 模块

Question

我正在使用带有 autodoc 扩展名的 Sphinx 为 Python 包自动生成文档。我面临的问题是 autodoc 会跳过任何带下划线的模块。

一些模块带有下划线以阻止用户导入它们。但是，这些带下划线的文件中的类没有下划线。

当我手动将带下划线的模块添加到 package_name.rst 和运行 make html 时，它会显示。所以我的问题是如何从 autodoc.

自动化

我试图避免通过脚本解析 package_name.rst 来添加它们。我希望有一个 autodoc 标记或 hack！

Answer 1

认为应用于包的 ..automodule :: 指令会自动将 sub-modules 记录为成员（与类、变量等相比）可能是一种误解。

我刚刚对此进行了测试，但无法使用 :private-members: and or :special-members:. Not by writing either option in the .. automodule:: directive corresponding to the package. (Trying to set both options in autodoc_default_options 给出相同的结果。）

包和模块布局示例如下：

C:.
│ 
└────your_package
   │
   │   public_module.py
   │   _private_module.py
   │   __init__.py

使用带有单个 .. automodule:: 的 .rst 包：

Your package rst
================

.. automodule:: your_package
    :members:
    :undoc-members:
    :private-members:
    :special-members:

带文档字符串的最小示例 _private_module.py（public_module.py 除标题外相同）：

"""Private module docstring."""

class PublicClass:
    """Docstring."""
    pass

确实给出了一个空文档：

但是如果您从模块中删除下划线，您会得到完全相同的结果。

I am trying to avoid parsing the package_name.rst via a script to add them

如果使用 -P 标志生成带有 sphinx-apidoc 的 .rst 文件：

-P, --private

Include “_private” modules. New in version 1.2.

生成的文件将包含私有模块的 .. automodule:: 指令，这确实有 side-effect 也包括另一个 post 中提到的 :private-members: 选项"Include __main__.py in sphinx-apidoc generated files".

示例明确包含 .. automodule:: 指令：

Your package rst
================

.. automodule:: your_package
    :members:
    :undoc-members:

    .. automodule:: your_package.public_module
        :members:
        :undoc-members:

    .. automodule:: your_package._private_module
        :members:
        :undoc-members:

结果：

如何使 Sphinx autodoc 扩展包含 underscore/private Python 模块

How to make Sphinx autodoc extension include an underscore/private Python module

python

python-sphinx

autodoc

sphinx-apidoc