Setuptools integration#

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

Deprecated since version 5.0: This feature will be removed in v7.0.

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),
            'source_dir': ('setup.py', 'doc')}},
)

Note

If you set Sphinx options directly in the setup() command, replace hyphens in variable names with underscores. In the example above, source-dir becomes source_dir.

Or add this section in setup.cfg:

[build_sphinx]
project = 'My project'
version = 1.2
release = 1.2.0
source-dir = 'doc'

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. It defaults to ./doc or ./docs if either contains a file named conf.py (checking ./doc first); otherwise it defaults to the current directory.

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 ./build/sphinx.

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 to use source-dir.

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.

link-index#

A boolean that ensures index.html will be linked to the root 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.

copyright#: The copyright string. Default is ''.

New in version 1.3.

nitpicky#: Run in nit-picky mode. Currently, this generates warnings for all missing references. See the config value nitpick_ignore for a way to exclude some references as “known missing”.

New in version 1.8.

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

New in version 1.5.