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
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/sphinx-users/e556a311-4f8e-48e8-9359-0065120118d5n%40googlegroups.com.
