Provided by: sphinx-common_1.7.9-1_all bug

NAME

       sphinx-build - Sphinx documentation generator tool

SYNOPSIS

       sphinx-build [options] <sourcedir> <outputdir> [filenames …]

DESCRIPTION

       sphinx-build  generates  documentation  from the files in <sourcedir> and places it in the
       <outputdir>.

       sphinx-build   looks   for   <sourcedir>/conf.py   for   the    configuration    settings.
       sphinx-quickstart(1) may be used to generate template files, including conf.py.

       sphinx-build  can  create  documentation  in  different  formats.  A format is selected by
       specifying the builder name on the command line; it defaults to HTML.  Builders  can  also
       perform other tasks related to documentation processing.

       By  default,  everything that is outdated is built.  Output only for selected files can be
       built by specifying individual filenames.

       For a list of available options, refer to sphinx-build -b.

OPTIONS

       -b buildername
              The most important option: it selects a builder.  The most common builders are:

              html   Build HTML pages.  This is the default builder.

              dirhtml
                     Build HTML pages, but with a  single  directory  per  document.   Makes  for
                     prettier URLs (no .html) if served from a webserver.

              singlehtml
                     Build a single HTML with the whole content.

              htmlhelp, qthelp, devhelp, epub
                     Build  HTML  files  with additional information for building a documentation
                     collection in one of these formats.

              applehelp
                     Build an Apple Help Book.  Requires hiutil and codesign, which are not  Open
                     Source and presently only available on Mac OS X 10.6 and higher.

              latex  Build LaTeX sources that can be compiled to a PDF document using pdflatex.

              man    Build manual pages in groff format for UNIX systems.

              texinfo
                     Build Texinfo files that can be processed into Info files using makeinfo.

              text   Build plain text files.

              gettext
                     Build gettext-style message catalogs (.pot files).

              doctest
                     Run all doctests in the documentation, if the doctest extension is enabled.

              linkcheck
                     Check the integrity of all external links.

              xml    Build Docutils-native XML files.

              pseudoxml
                     Build  compact  pretty-printed  “pseudo-XML”  files  displaying the internal
                     structure of the intermediate document trees.

              See builders for a list of all builders shipped with Sphinx.   Extensions  can  add
              their own builders.

       -M buildername
              Alternative  to -b. Uses the Sphinx make_mode module, which provides the same build
              functionality as a  default  Makefile  or  Make.bat.  In  addition  to  all  Sphinx
              builders, the following build pipelines are available:

              latexpdf
                     Build  LaTeX  files  and  run  them through pdflatex, or as per latex_engine
                     setting.   If  language  is  set  to  'ja',  will  use   automatically   the
                     platex/dvipdfmx latex to PDF pipeline.

              info   Build Texinfo files and run them through makeinfo.

              IMPORTANT:
                 Sphinx only recognizes the -M option if it is placed first.

              New in version 1.2.1.

       -a     If  given, always write all output files. The default is to only write output files
              for new and changed source files. (This may not apply to all builders.)

       -E     Don’t use a saved environment (the structure  caching  all  cross-references),  but
              rebuild it completely.  The default is to only read and parse source files that are
              new or have changed since the last run.

       -t tag Define the tag tag.  This is relevant for only directives that only  include  their
              content if this tag is set.

              New in version 0.6.

       -d path
              Since  Sphinx  has to read and parse all source files before it can write an output
              file, the parsed source files are cached as  “doctree  pickles”.   Normally,  these
              files  are put in a directory called .doctrees under the build directory; with this
              option you can select a different cache  directory  (the  doctrees  can  be  shared
              between all builders).

       -j N   Distribute   the   build  over  N  processes  in  parallel,  to  make  building  on
              multiprocessor machines more effective.  Note  that  not  all  parts  and  not  all
              builders of Sphinx can be parallelized.  If auto argument is given, Sphinx uses the
              number of CPUs as N.

              New in version 1.2: This option should be considered experimental.

              Changed in version 1.7: Support auto argument.

       -c path
              Don’t look for the conf.py in the source directory, but use the given configuration
              directory  instead.  Note that various other files and paths given by configuration
              values are expected to be relative to the configuration  directory,  so  they  will
              have to be present at this location too.

              New in version 0.3.

       -C     Don’t look for a configuration file; only take options via the -D option.

              New in version 0.5.

       -D setting=value
              Override  a  configuration  value  set  in  the  conf.py file.  The value must be a
              number, string, list or dictionary value.

              For  lists,  you   can   separate   elements   with   a   comma   like   this:   -D
              html_theme_path=path1,path2.

              For   dictionary   values,   supply   the  setting  name  and  key  like  this:  -D
              latex_elements.docclass=scrartcl.

              For boolean values, use 0 or 1 as the value.

              Changed in version 0.6: The value can now be a dictionary value.

              Changed in version 1.3: The value can now also be a list value.

       -A name=value
              Make the name assigned to value in the HTML templates.

              New in version 0.5.

       -n     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”.

       -N     Do not emit colored output.

       -v     Increase verbosity (loglevel).  This option can be given up to three times  to  get
              more debug logging output.  It implies -T.

              New in version 1.2.

       -q     Do  not  output  anything  on  standard  output,  only write warnings and errors to
              standard error.

       -Q     Do not output anything on standard output, also suppress warnings.  Only errors are
              written to standard error.

       -w file
              Write warnings (and errors) to the given file, in addition to standard error.

       -W     Turn  warnings  into  errors.  This means that the build stops at the first warning
              and sphinx-build exits with exit status 1.

       -T     Display the full traceback when an unhandled exception occurs.  Otherwise,  only  a
              summary  is  displayed and the traceback information is saved to a file for further
              analysis.

              New in version 1.2.

       -P     (Useful for debugging only.)   Run  the  Python  debugger,  pdb,  if  an  unhandled
              exception occurs while building.

       -h, --help, --version
              Display usage summary or Sphinx version.

              New in version 1.2.

       You  can  also  give  one or more filenames on the command line after the source and build
       directories.  Sphinx  will  then  try  to  build  only  these  output  files  (and   their
       dependencies).

ENVIRONMENT VARIABLES

       The sphinx-build refers following environment variables:

       MAKE   A  path  to make command.  A command name is also allowed.  sphinx-build uses it to
              invoke sub-build process on make-mode.
       Makefile Options

       The Makefile and make.bat files created by sphinx-quickstart usually run sphinx-build only
       with  the  -b  and -d options.  However, they support the following variables to customize
       behavior:

       PAPER  This sets the 'papersize' key of latex_elements: i.e. PAPER=a4 sets it to 'a4paper'
              and PAPER=letter to 'letterpaper'.

              NOTE:
                 Usage  of  this  environment  variable  got broken at Sphinx 1.5 as a4 or letter
                 ended up as option to LaTeX document in  place  of  the  needed  a4paper,  resp.
                 letterpaper.  Fixed at 1.7.7.

       SPHINXBUILD
              The command to use instead of sphinx-build.

       BUILDDIR
              The build directory to use instead of the one chosen in sphinx-quickstart.

       SPHINXOPTS
              Additional options for sphinx-build.

DEPRECATION WARNINGS

       If  any  deprecation  warning like RemovedInSphinxXXXWarning are displayed when building a
       user’s document, some Sphinx extension is using deprecated features. In that case,  please
       report it to author of the extension.

       To  disable  the  deprecation warnings, please set PYTHONWARNINGS= environment variable to
       your environment. For example:

       · PYTHONWARNINGS= make html (Linux/Mac)

       · export PYTHONWARNINGS= and do make html (Linux/Mac)

       · set PYTHONWARNINGS= and do make html (Windows)

       · modify your Makefile/make.bat and set the environment variable

SEE ALSO

       sphinx-quickstart(1)

COPYRIGHT

       2007-2018, Georg Brandl and the Sphinx team