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),
'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
orsetup.cfg
file, or it can be absolute. It defaults to./doc
or./docs
if either contains a file namedconf.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
orsetup.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
orsetup.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 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.
-
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.