On Monday, June 28, 2021 at 3:13:30 PM UTC-4 John Snow wrote: > 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. >
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 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/a131fe82-6e51-4af3-82f7-94e28419c460n%40googlegroups.com.
