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

Question

The code base I'm working with is structured under a namespace . I'm responsible for namespace.my_project , but I depend on various other modules from namespace . Is there any way to tell Sphinx (with autodoc) to document namespace.my_project , but ignore everything directly under namespace ?

I've tried adding exactly the module I want to index.rst :

.. toctree::
    namespace.my_project

This shows up fine in the final documentation, but during compilation I still get a lot of warnings from members of namespace that I don't have control over.

Answer 1

There aren't many options for this, using the autodoc extension it imports your objects with the normal Python importing rules.

sphinx.ext.autodoc – Include documentation from docstrings

This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way.

So, you would have to selectivly write your .rst files using autodoc directives that import only what you want. From your example, assuming my_project is structured as a package, this could be relativly easy, you would write:

.. automodule:: namespace.my_project

or lets say you have 2 different packages within my_project

.. automodule:: namespace.my_project.my_package1

.. automodule:: namespace.my_project.my_package2

Basically you've imported only the modules/objects from the project that interest you. Then in the .. toctree:: directive you would include only .rst files that have these carefully chosen directives.

This does have a few drawbacks however, all the objects in the namespace that you don't explicitly document would not be included in the index and would not be cross-referenceable (unless you created empty .rst declarations with domain directives ). They would, however, be rendered textually without links and assuming there are no underlying Python errors the documentation would build normally without warnings.