Sphinx autodoc 文档 namespace.module 可以不记录命名空间吗？

Question

我正在使用的代码库是在namespace下构建的。 我负责namespace.my_project ，但我依赖于namespace各种其他模块。 有什么方法可以告诉 Sphinx（使用 autodoc）记录namespace.my_project ，但直接忽略namespace下的所有内容？

我试过准确添加我想要index.rst的模块：

.. toctree::
    namespace.my_project

这在最终文档中显示得很好，但在编译过程中，我仍然从namespace成员那里收到很多我无法控制的警告。

Answer 1

对此没有太多选择，使用 autodoc 扩展，它使用普通的 Python 导入规则导入您的对象。

sphinx.ext.autodoc – 包含文档字符串中的文档

这个扩展可以导入你正在记录的模块，并以半自动的方式从文档字符串中提取文档。

因此，您必须使用仅导入您想要的内容的 autodoc 指令有选择地编写.rst文件。 从您的示例中，假设my_project被构造为一个包，这可能相对容易，您可以编写：

.. automodule:: namespace.my_project

或者假设您在my_project有 2 个不同的包

.. automodule:: namespace.my_project.my_package1

.. automodule:: namespace.my_project.my_package2

基本上，您只从您感兴趣的项目中导入了模块/对象。 然后在.. toctree::指令中，您将只包含具有这些精心选择的指令的.rst文件。

但是，这确实有一些缺点，您未明确记录的名称空间中的所有对象都不会包含在索引中，也不会交叉引用（除非您使用域指令创建了空的.rst声明）。 然而，它们将在没有链接的情况下以文本形式呈现，并且假设没有潜在的 Python 错误，文档将正常构建而不会发出警告。