Sphinx autodoc and re-exported modules from __all__

42 views
Skip to first unread message

John Snow

unread,
Jun 28, 2021, 3:13:30 PMJun 28
to sphinx-users
Hello all, greetings from the QEMU upstream.

In short, my question is how do I convince "automodule" to not create cross-referenceable targets for things imported and re-exported by __all__. I'd like to still show the documentation on the generated page, but I do not want it to be considered as a possible match when using the "any" cross-reference role.

In more detail:

I am working on generating Sphinx documentation for our Python package. I have a subpackage I am currently developing where I have a structure like this:

qemu/     (PEP 420 namespace)
  aqmp/
    __init__.py
    error.py
    message.py
    protocol.py

the __init__.py file imports classes, exceptions, and so on that are anticipated to be the most crucial for a standard user of the library and re-exports them via __all__. This way it's possible to type "from qemu.aqmp import QMP", and so on.

sphinx-apidoc generates stubs for qemu.aqmp in a manner where it uses "automodule" to document this module, but it has the side-effect of producing ambiguous cross-reference targets for the "any" role. Anything imported by __init__ becomes inherently ambiguous and generates warnings when building the docs.

Is it at all possible to somehow coerce automodule to still generate the documentation but without including those generated items as possible cross-referenceable targets?

My workaround for now is (so far) to just delete the automodule directive from qemu.aqmp.rst entirely to prevent any cross-reference conflicts.

Thank you in advance for any help or advice,
--John Snow, QEMU Python library maintainer

John Snow

unread,
Jun 30, 2021, 11:56:32 AMJun 30
to sphinx-users
Figured this one out.

You can use :noindex: on the module in question to show docs but avoiding creating ambiguous targets for it. You could also use :ignore-module-all: to avoid generating them entirely if you wish.
 
--js
Reply all
Reply to author
Forward
0 new messages