StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POAutomatically Generating Documentation for All Python Package Contents
text
Body
copied!<p>I'm trying to auto-generate basic documentation for my codebase using Sphinx. However, I'm having difficulty instructing Sphinx to recursively scan my files.</p> <p>I have a Python codebase with a folder structure like:</p> <pre><code><workspace> src mypackage __init__.py subpackageA __init__.py submoduleA1 submoduleA2 subpackageB __init__.py submoduleB1 submoduleB2 </code></pre> <p>I ran sphinx-quickstart in <code><workspace></code>, so now my structure looks like:</p> <pre><code><workspace> src mypackage __init__.py subpackageA __init__.py submoduleA1 submoduleA2 subpackageB __init__.py submoduleB1 submoduleB2 index.rst _build _static _templates </code></pre> <p>I've read the quickstart tutorial <a href="http://sphinx.pocoo.org/tutorial.html">http://sphinx.pocoo.org/tutorial.html</a>, and although I'm still trying to understand the docs, the way it's worded makes me concerned that Sphinx assumes I'm going to manually create documentation files for every single module/class/function in my codebase.</p> <p>However, I did notice the "automodule" statement, and I enabled autodoc during quickstart, so I'm hoping most of the documentation can be automatically generated. I modified my conf.py to add my src folder to sys.path and then modified my index.rst to use automodule. So now my index.rst looks like:</p> <pre><code>Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. automodule:: alphabuyer :members: </code></pre> <p>I have dozens of classes and functions defined in the subpackages. Yet, when I run:</p> <pre><code>sphinx-build -b html . ./_build </code></pre> <p>it reports:</p> <pre><code>updating environment: 1 added, 0 changed, 0 removed </code></pre> <p>And this appears to have failed to import anything inside my package. Viewing the generated index.html shows nothing next to "Contents:". The Index page only shows "mypackage (module)", but clicking it shows it also has no contents.</p> <p>How do you direct Sphinx to recursively parse a package and automatically generate documentation for every class/method/function it encounters, without having to manually list every class yourself?</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload