Setuptools integration

Sphinx supports integration with setuptools and distutils through a custom command - BuildDoc.

Using setuptools integration

The Sphinx build can then be triggered from distutils, and some Sphinx options can be set in setup.py or setup.cfg instead of Sphinx’s own configuration file.

For instance, from setup.py:

# this is only necessary when not using setuptools/distribute
from sphinx.setup_command import BuildDoc
cmdclass = {'build_sphinx': BuildDoc}

name = 'My project'
version = '1.2'
release = '1.2.0'
setup(
    name=name,
    author='Bernard Montgomery',
    version=release,
    cmdclass=cmdclass,
    # these are optional and override conf.py settings
    command_options={
        'build_sphinx': {
            'project': ('setup.py', name),
            'version': ('setup.py', version),
            'release': ('setup.py', release)}},
)

Or add this section in setup.cfg:

[build_sphinx]
project = 'My project'
version = 1.2
release = 1.2.0

Once configured, call this by calling the relevant command on setup.py:

$ python setup.py build_sphinx

Options for setuptools integration

fresh-env

A boolean that determines whether the saved environment should be discarded on build. Default is false.

This can also be set by passing the -E flag to setup.py.

$ python setup.py build_sphinx -E
all-files

A boolean that determines whether all files should be built from scratch. Default is false.

This can also be set by passing the -a flag to setup.py:

$ python setup.py build_sphinx -a
source-dir

The target source directory. This can be relative to the setup.py or setup.cfg file, or it can be absolute. Default is ''.

This can also be set by passing the -s flag to setup.py:

$ python setup.py build_sphinx -s $SOURCE_DIR
build-dir

The target build directory. This can be relative to the setup.py or setup.cfg file, or it can be absolute. Default is ''.

config-dir

Location of the configuration directory. This can be relative to the setup.py or setup.cfg file, or it can be absolute. Default is ''.

This can also be set by passing the -c flag to setup.py:

$ python setup.py build_sphinx -c $CONFIG_DIR

New in version 1.0.

builder

The builder or list of builders to use. Default is html.

This can also be set by passing the -b flag to setup.py:

$ python setup.py build_sphinx -b $BUILDER

Changed in version 1.6: This can now be a comma- or space-separated list of builders

warning-is-error

A boolean that ensures Sphinx warnings will result in a failed build. Default is false.

This can also be set by passing the -W flag to setup.py:

$ python setup.py build_sphinx -W

New in version 1.5.

project

The documented project’s name. Default is ''.

New in version 1.0.

version

The short X.Y version. Default is ''.

New in version 1.0.

release

The full version, including alpha/beta/rc tags. Default is ''.

New in version 1.0.

today

How to format the current date, used as the replacement for |today|. Default is ''.

New in version 1.0.

A boolean that ensures index.html will be linked to the master doc. Default is false.

This can also be set by passing the -i flag to setup.py:

$ python setup.py build_sphinx -i

New in version 1.0.

The copyright string. Default is ''.

New in version 1.3.

pdb

A boolean to configure pdb on exception. Default is false.

New in version 1.5.