python - 如何使 Sphinx 自动文档扩展包含下划线/私有 Python 模块

Question

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

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

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

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

标签： pythonpython-sphinxautodocsphinx-apidoc

Answer 1

认为..automodule ::应用于包的指令会自动将子模块记录为成员（通过与类、变量等进行比较）可能是一种误解。

我刚刚对此进行了测试，但无法使用:private-members:and or:special-members:来完成。不是通过在.. automodule::与包对应的指令中写入任何一个选项。（尝试同时设置两个选项autodoc_default_options会得到相同的结果。）

以下包和模块布局示例：

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

将 a.rst与单个.. automodule::包装一起使用：

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

确实给出了一个空文档：

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

我试图避免通过脚本解析 package_name.rst 来添加它们

如果您使用if标志生成.rst文件：sphinx-apidoc-P

-P，--私人

包括“_private”模块。1.2 版中的新功能。

生成的文件将包含.. automodule::私有模块的指令，这确实具有包含选项的副作用，:private-members:如另一篇文章“在 sphinx-apidoc 生成的文件中包含 __main__.py”中所述。

明确包含.. 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:

结果：