sphinx-build(1) - Man pages

SPHINX-BUILD(1) Sphinx SPHINX-BUILD(1)

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 set-
tings. sphinx-quickstart(1) may be used to generate template files, in-
cluding 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 Builders.

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

OPTIONS
-M buildername
Select a builder, using the make-mode. See Builders for a list
of all of Sphinx's built-in builders. Extensions can add their
own builders.

IMPORTANT:
Sphinx only recognizes the -M option if it is used first,
along with the source and output directories, before any other
options are passed. For example:

sphinx-build -M html ./source ./build --fail-on-warning

The make-mode provides the same build functionality as a default
Makefile or Make.bat, and provides the following additional build
pipelines:

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.

NOTE:
The default output directory locations when using make-mode
differ from the defaults when using -b.

• doctrees are saved to <outputdir>/doctrees

• output files are saved to <outputdir>/<builder name>

Added in version 1.2.1.

-b buildername, --builder buildername
Selects a builder.

See Builders for a list of all of Sphinx's built-in builders.
Extensions can add their own builders.

Changed in version 7.3: Add --builder long option.

-a, --write-all
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.)

NOTE:
This option does not re-read source files. To read and
re-process every file, use --fresh-env instead.

Changed in version 7.3: Add --write-all long option.

-E, --fresh-env
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.

Changed in version 7.3: Add --fresh-env long option.

-t tag, --tag tag
Define the tag tag. This is relevant for only directives that
include their content only if certain tags are set. See
including content based on tags for further detail.

Added in version 0.6.

Changed in version 7.3: Add --tag long option.

-d path, --doctree-dir 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 "doc-
tree 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).

Changed in version 7.3: Add --doctree-dir long option.

-j N, --jobs N
Distribute the build over N processes in parallel, to make build-
ing on multiprocessor machines more effective. This feature only
works on systems supporting "fork". Windows is not supported.
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. Defaults to 1.

Added in version 1.2: This option should be considered experimen-
tal.

Changed in version 1.7: Support auto argument.

Changed in version 6.2: Add --jobs long option.

-c path, --config-dir 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.

Added in version 0.3.

Changed in version 7.3: Add --config-dir long option.

-C, --isolated
Don't look for a configuration file; only take options via the
--define option.

Added in version 0.5.

Changed in version 7.3: Add --isolated long option.

-D setting=value, --define 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.

Changed in version 7.3: Add --define long option.

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

Added in version 0.5.

Changed in version 7.3: Add --html-define long option.

-n, --nitpicky
Run in nitpicky 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".

Changed in version 7.3: Add --nitpicky long option.

-N, --no-color
Do not emit colored output.

Changed in version 1.6: Add --no-color long option.

--color
Emit colored output. Auto-detected by default.

Added in version 1.6.

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

Added in version 1.2.

Changed in version 7.3: Add --verbose long option.

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

Changed in version 7.3: Add --quiet long option.

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

Changed in version 7.3: Add --silent long option.

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

Changed in version 7.3: ANSI control sequences are stripped when
writing to file.

Changed in version 7.3: Add --warning-file long option.

-W, --fail-on-warning
Turn warnings into errors. This means that sphinx-build exits
with exit status 1 if any warnings are generated during the
build.

Changed in version 7.3: Add --fail-on-warning long option.

Changed in version 8.1: sphinx-build no longer exits on the first
warning, but instead runs the entire build and exits with exit
status 1 if any warnings were generated. This behaviour was pre-
viously enabled with --keep-going.

--keep-going
From Sphinx 8.1, --keep-going is always enabled. Previously, it
was only applicable whilst using --fail-on-warning, which by de-
fault exited sphinx-build on the first warning. Using --keep-go-
ing runs !sphinx-build to completion and exits with exit status 1
if errors are encountered.

Added in version 1.8.

Changed in version 8.1: sphinx-build no longer exits on the first
warning, meaning that in effect --fail-on-warning is always en-
abled. The option is retained for compatibility, but may be re-
moved at some later date.

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

Added in version 1.2.

Changed in version 7.3: Add --show-traceback long option.

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

Changed in version 7.3: Add --pdb long option.

--exception-on-warning
Raise an exception when a warning is emitted during the build.
This can be useful in combination with --pdb to debug warnings.

Added in version 8.1.

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

Added 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').

NO_COLOR
When set (regardless of value), sphinx-build will not use color
in terminal output. NO_COLOR takes precedence over FORCE_COLOR.
See ]8;;https://no-color.org/\no-color.org]8;;\ for other libraries supporting this community
standard.

Added in version 4.5.0.

FORCE_COLOR
When set (regardless of value), sphinx-build will use color in
terminal output. NO_COLOR takes precedence over FORCE_COLOR.

Added in version 4.5.0.

DEPRECATION WARNINGS
If any deprecation warning like RemovedInSphinxXXXWarning are displayed
when building a user's document, some Sphinx extension is using depre-
cated features. In that case, please report it to author of the exten-
sion.

To disable the deprecation warnings, please set PYTHONWARNINGS= environ-
ment 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