Sphinx autodoc is not automatic enough

python python-sphinx autodoc
Cory Walker picture Cory Walker · Apr 23, 2010 · Viewed 44k times · Source

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.

Answer

Etienne picture Etienne · Apr 24, 2010

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 questions

sphinx-build fail - autodoc can't import/find module

I'm trying to get started with Sphinx and seem to have relentless problems. Command: docs/sphinx-quickstart I answer all the questions and everything works fine. Command: docs/ls Everything looks normal. Result: build Makefile source Command: sphinx-build -d build/doctrees …

Read More
How to use Sphinx's autodoc to document a class's __init__(self) method?

Sphinx doesn't generate docs for __init__(self) by default. I have tried the following: .. automodule:: mymodule :members: and ..autoclass:: MyClass :members: In conf.py, setting the following only appends the __init__(self) docstring to the class docstring (the Sphinx autodoc …

Read More
What is the correct way to document a **kwargs parameter?

I'm using sphinx and the autodoc plugin to generate API documentation for my Python modules. Whilst I can see how to nicely document specific parameters, I cannot find an example of how to document a **kwargs parameter. Does anyone have …

Read More