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