Python – Sphinx autodoc is not automatic enough

autodocpythonpython-sphinx

I'm trying to use Sphinx to document a 5,000+ line project in Python. It has about 7 base modules. As far as I know, In order to use autodoc I need to write code like this for each file in my project:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

This is way too tedious because I have many files. It would be much easier if I could just specify that I wanted the 'mods' package to be documented. Sphinx could then recursively go through the package and make a page for each submodule.

Is there a feature like this? If not I could write a script to make all the .rst files, but that would take up a lot of time.

Best Answer

~~You can check this script that I've made. I think it can help you.~~

This script parses a directory tree looking for python modules and packages and creates ReST files appropriately to create code documentation with Sphinx. It also creates a modules index.

UPDATE

This script is now part of Sphinx 1.1 as apidoc.

Related Solutions

Python – How to cross-reference a function generated by autodoc in Sphinx

You don't need to add labels. In order to refer to a Python class, method, or other documented object, use the markup provided by the Python domain.

For example, the following defines a cross-reference to the mymethod method:

:py:meth:`mymodule.MyClass.mymethod`

Or even simpler (since the Python domain is the default):

:meth:`mymodule.MyClass.mymethod`

The documentation of TextWrapper.wrap that you link to in the question includes two cross-references of this kind (click on "Show Source" to see the reST markup).

Python – sphinx-apidoc picks up submodules, but autodoc doesn’t document them

I ended up fixing this problem eventually - it seems I was overlooking some errors, and sphinx worked just fine. I added all the paths the package contains in the conf.py and it just worked from there:

conf.py:

sys.path.insert(0, os.path.abspath('../StyledPyQt5'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt/core'))
sys.path.insert(0, os.path.abspath('../StyledPyQt5/styledpyqt/core/base'))

From there, everything worked.

It's important to note here that I generate my docs in a separate directory from my code. If you're using sphinx-apidoc to generate your .rst files, and you're using a gh-pages branch for documentation like I am, don't forget to generate your HTML pages separately while you're on the master branch. Otherwise, there won't be any code to source from. My workflow looks like this now:

make sure i'm on the master branch by running git checkout master
run sphinx-apidoc -F -P -o ..output_dir ..source_dir, where output_dir is not the same as source_dir.
run make html, making sure that _build/html is in a directory that isn't in either branch of my repo.
run git checkout gh-pages to switch to my gh-pages branch, removing code files and replacing them with html documentation pages.
copy all newly generated HTML files in _build/html to the gh-pages main folder, overwriting any changes.
run git commit -am "Docs Update" gh-pages to commit the changes
run git push origin gh-pages to push the commit to github
run git checkout master to put me back on the master branch

I know there's a dime a dozen tutorials out there documenting this, but I hope this small elaboration might help someone at some point.

Best Answer

Related Solutions

Python – How to cross-reference a function generated by autodoc in Sphinx

Python – sphinx-apidoc picks up submodules, but autodoc doesn’t document them

Related Topic