- Home
- Get it
- Docs
- Extend/Develop

# 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.

`link-index`

  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.

`copyright`

  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.