Autogenerate documentation for Python project using setuptools

Question

I have created a demo project which uses setuptools and has the following structure:

project/
 |- pizza/
 |   |- __init__.py
 |   `- margherita.py
 |
 |- README.rst
 |- setup.cfg
 `- setup.py

I'm trying to autogenerate documentation for this project using Sphinx. So far I've tried:

# Generate a sphinx template
sphinx-quickstart
# Use default settings, except for project name, etc.
sphinx-apidoc -o source .
./setup.py build_sphinx

I feel there has to be an easier way to autogenerate this documentation using the README, setup.py and docstrings.

Ultimately I'd like to autogenerate apidocs for another project where I use the Python C-api as well. I couldn't find anything for this.

My main question is: Is there an easier way to autogenerate this documentation?

Answer 1

sphinx-apidoc -F -o source .

Will generate a project with sphinx-quickstart and recursively look for python modules

You're about as efficient as you can be at the moment.

=== Just wishful thinking below here ===

Wouldn't it be lovely if you could call something like

./setup.py build_sphinx -C

and it would create you index.RST, read any RST files you had knocking about, parse all the docstrings and spit out some html.

Answer 2

To extend setup.py so it contains an extra command for Sphinx, you could create a custom command. I've cooked up a small example that runs Sphinx apidoc and then builds the doc sources. The project name, author, version and location of the sources defined in the setup.py are used (assuming they are defined).

class Sphinx(Command):
    user_options = []
    description = 'sphinx'

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    def run(self):
        # metadata contains information supplied in setup()
        metadata = self.distribution.metadata
        # package_dir may be None, in that case use the current directory.
        src_dir = (self.distribution.package_dir or {'': ''})['']
        src_dir = os.path.join(os.getcwd(),  src_dir)
        # Run sphinx by calling the main method, '--full' also adds a conf.py
        sphinx.apidoc.main(
            ['', '--full', '-H', metadata.name, '-A', metadata.author,
             '-V', metadata.version, '-R', metadata.version,
             '-o', os.path.join('doc', 'source'), src_dir])
        # build the doc sources
        sphinx.main(['', os.path.join('doc', 'source'),
                     os.path.join('doc', 'build')])

Then the command needs to be registered to the entry point group distutils.commands. Here the command is called sphinx.

from setuptools import setup

setup(
    # ...
    setup_requires = ['sphinx'],
    entry_points = {
        'distutils.commands': [
            'sphinx = example_module:Sphinx'
        ]
    }
)

I don't know how C sources are handled, but this'll get you started.