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 – Include documentation from docstrings

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

因此，您必须使用仅导入您想要的内容的 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 声明domain directives）。然而，它们将在没有链接的情况下以文本形式呈现，并且假设没有潜在的 Python 错误，文档将正常构建而不会发出警告。