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?

score 7 · Answer 1 · answered Mar 08 '14 at 18:17

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.

This was incredibly helpful. Thank you – dusktreader Aug 24 '16 at 21:45 — dusktreader, Aug 24 '16 at 21:45

score 3 · Accepted Answer · answered Jan 20 '14 at 10:48

3

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.

answered Jan 20 '14 at 10:48

Chris Clarke

2,103
2
14
19

Also the following flags will include some metadata: `-H $(./setup.py --name) -A $(./setup.py --author) -V $(./setup.py --version)`. Unfortunately this does not work for C extensions. – Remco Haszing Jan 20 '14 at 16:29
I'm sorry, but this is quite an easy answer. I don't spot any effort to create a neat solution of some kind. The example you state (`/.setup.py build_sphinx -C`) looks right. This should be possible one way or another. Simply stating the use of `sphinx-apidoc` is not worth my bounty. – siebz0r Jan 21 '14 at 08:00
Agreed, good luck finding a more elegant solution. I'd like to know if you do – Chris Clarke Jan 21 '14 at 17:15

Autogenerate documentation for Python project using setuptools

2 Answers2