Sphinx, using automodule to find submodules

Question

When using sphinx's automodule (https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html),

I simply write in a .rst file:

.. automodule:: my_module
    :members:

It documents my_module fine, but it doesn't find the inner modules like my_module.inner_module0 and my_module.inner_module1. Is there something that needs to be specified in the __init__.py file besides the __all__ variable?

Also, I'm aware of sphinx-apidoc. But that command documents far too much (exposes every function/folder including undocumented ones).

score 42 · Answer 1 · answered Jul 19 '12 at 19:49

It sounds like you want to give the automodule directive a package name and have it recurse into the directory and document each Python module. That isn't supported yet. You will ned to specify the full dotted module name for each module you want to document.

For example, given the following directory structure (from the Python documentation). You cannot specify .. automodule:: sound.formats and have it document all the modules in the directory. You will have to specify a automodule command for each module: .. automodule:: sound.formats.waveread, .. automodule:: sound.formats.wavewrite, etc.

sound/                          Top-level package
      __init__.py               Initialize the sound package
      formats/                  Subpackage for file format conversions
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      effects/                  Subpackage for sound effects
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...

This is a pretty old answer now. Is it still the case that there's no auto-discovery? — naught101, Jan 10 '19 at 03:18
@naught101 in particular this [related thread](https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough?rq=1) can be interesting. — Ivo Merchiers, Oct 14 '20 at 11:31

Noel Maersk · Answer 2 · 2017-03-27T10:49:23.317

6

It seems to me that using the :imported-members: option (non-direct link, do use search) should now be possible, if __init__.py imports those submodules.

However, I'm personally not able to make this work (yet).

EDIT: Possibly a known bug.

edited Mar 27 '17 at 10:49

answered Mar 27 '17 at 10:31

Noel Maersk

169
1
5

I don't think this is solved by using `imported-members`. IMHO, @devin_s's highly upvoted answer is the correct one (or at least on the right track). The asker has not been active on Stack Overflow since August 2013, so it seems unlikely that we will get a confirmation from him. – mzjn Mar 27 '17 at 11:13
True... Re-read question, seems that I misunderstood it, interpreting through the lens of my own task. Sorry for the noise. – Noel Maersk Mar 30 '17 at 11:11

Sphinx, using automodule to find submodules

2 Answers2

Linked