Provided by: sphinx-common_4.3.2-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.   For  a  list of available
       builders, refer to sphinx-build -b.

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

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  /usage/builders/index  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
              /usage/builders/index, 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.

       --keep-going
              With  -W  option,  keep going processing when getting warnings to the end of build,
              and sphinx-build exits with exit status 1.

              New in version 1.8.

       -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. These options can also be set via the shortcut
              variable O (capital 'o').

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-2021, Georg Brandl and the Sphinx team