如何使 Sphinx autodoc 扩展包含下划线/私有 Python 模块

Question

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

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

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

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

Answer 1

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

\n

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

\n

以下是封装和模块布局的示例：

\n

C:.\n\xe2\x94\x82 \n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80your_package\n   \xe2\x94\x82\n   \xe2\x94\x82   public_module.py\n   \xe2\x94\x82   _private_module.py\n   \xe2\x94\x82   __init__.py\n

\n

使用 a.rst和 single.. automodule::作为包：

\n

Your package rst\n================\n\n.. automodule:: your_package\n    :members:\n    :undoc-members:\n    :private-members:\n    :special-members:\n

\n

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

\n

C:.\n\xe2\x94\x82 \n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80your_package\n   \xe2\x94\x82\n   \xe2\x94\x82   public_module.py\n   \xe2\x94\x82   _private_module.py\n   \xe2\x94\x82   __init__.py\n

\n

确实给出了一个空文档：

\n

\n

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

\n

\n

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

\n

\n

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

\n

\n

-P, --私人

\n

包括 \xe2\x80\x9c_private\xe2\x80\x9d 模块。\n版本 1.2 中的新增功能。

\n

\n

生成的文件将包含.. automodule::私有模块的指令，这确实会产生副作用，因为还包含:private-members:另一篇文章“在 sphinx-apidoc 生成的文件中包含 __main__.py”中提到的选项。

\n

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

\n

Your package rst\n================\n\n.. automodule:: your_package\n    :members:\n    :undoc-members:\n\n    .. automodule:: your_package.public_module\n        :members:\n        :undoc-members:\n\n    .. automodule:: your_package._private_module\n        :members:\n        :undoc-members:\n

\n

结果：

\n

\n