summaryrefslogtreecommitdiffstats
path: root/doc/man/sphinx-build.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/sphinx-build.rst')
-rw-r--r--doc/man/sphinx-build.rst191
1 files changed, 107 insertions, 84 deletions
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
index a1fb9be..8be2780 100644
--- a/doc/man/sphinx-build.rst
+++ b/doc/man/sphinx-build.rst
@@ -20,7 +20,7 @@ files, including ``conf.py``.
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
-:option:`sphinx-build -b`.
+:doc:`/usage/builders/index`.
By default, everything that is outdated is built. Output only for selected
files can be built by specifying individual filenames.
@@ -30,107 +30,87 @@ Options
.. program:: sphinx-build
-.. option:: -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 :program:`hiutil` and
- :program:`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
- :program:`pdflatex`.
-
- **man**
- Build manual pages in groff format for UNIX systems.
-
- **texinfo**
- Build Texinfo files that can be processed into Info files using
- :program:`makeinfo`.
-
- **text**
- Build plain text files.
-
- **gettext**
- Build gettext-style message catalogs (``.pot`` files).
-
- **doctest**
- Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
- extension is enabled.
-
- **linkcheck**
- Check the integrity of all external links.
+.. _make_mode:
- **xml**
- Build Docutils-native XML files.
+.. option:: -M buildername
- **pseudoxml**
- Build compact pretty-printed "pseudo-XML" files displaying the
- internal structure of the intermediate document trees.
+ Select a builder, using the *make-mode*.
+ See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders.
+ Extensions can add their own builders.
- See :doc:`/usage/builders/index` for a list of all builders shipped with
- Sphinx. 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::
-.. _make_mode:
+ sphinx-build -M html ./source ./build -W --keep-going
-.. option:: -M buildername
+ The *make-mode* provides the same build functionality as
+ a default :ref:`Makefile or Make.bat <makefile_options>`,
+ and provides the following additional build pipelines:
- Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module,
- which provides the same build functionality as a default :ref:`Makefile or
- Make.bat <makefile_options>`. In addition to all Sphinx
- :doc:`/usage/builders/index`, the following build pipelines are available:
-
- **latexpdf**
+ *latexpdf*
Build LaTeX files and run them through :program:`pdflatex`, or as per
:confval:`latex_engine` setting.
If :confval:`language` is set to ``'ja'``, will use automatically
the :program:`platex/dvipdfmx` latex to PDF pipeline.
- **info**
+ *info*
Build Texinfo files and run them through :program:`makeinfo`.
- .. important::
- Sphinx only recognizes the ``-M`` option if it is placed first.
+ .. note::
+
+ The default output directory locations when using *make-mode*
+ differ from the defaults when using :option:`-b`.
+
+ * doctrees are saved to ``<outputdir>/doctrees``
+ * output files are saved to ``<outputdir>/<builder name>``
.. versionadded:: 1.2.1
-.. option:: -a
+.. option:: -b buildername, --builder buildername
+
+ Selects a builder.
+
+ See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders.
+ Extensions can add their own builders.
+
+ .. versionchanged:: 7.3
+ Add ``--builder`` long option.
+
+.. 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.)
-.. option:: -E
+ .. note:: This option does not re-read source files.
+ To read and re-process every file,
+ use :option:`--fresh-env` instead.
+
+ .. versionchanged:: 7.3
+ Add ``--write-all`` long option.
+
+.. option:: -E, --fresh-env
Don't use a saved :term:`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.
-.. option:: -t tag
+ .. versionchanged:: 7.3
+ Add ``--fresh-env`` long option.
+
+.. option:: -t tag, --tag tag
Define the tag *tag*. This is relevant for :rst:dir:`only` directives that
only include their content if this tag is set.
.. versionadded:: 0.6
-.. option:: -d path
+ .. versionchanged:: 7.3
+ Add ``--tag`` long option.
+
+.. 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 "doctree pickles".
@@ -138,6 +118,9 @@ Options
the build directory; with this option you can select a different cache
directory (the doctrees can be shared between all builders).
+ .. versionchanged:: 7.3
+ Add ``--doctree-dir`` long option.
+
.. option:: -j N, --jobs N
Distribute the build over *N* processes in parallel, to make building on
@@ -154,7 +137,7 @@ Options
.. versionchanged:: 6.2
Add ``--jobs`` long option.
-.. option:: -c path
+.. option:: -c path, --config-dir path
Don't look for the :file:`conf.py` in the source directory, but use the given
configuration directory instead. Note that various other files and paths
@@ -164,13 +147,19 @@ Options
.. versionadded:: 0.3
-.. option:: -C
+ .. versionchanged:: 7.3
+ Add ``--config-dir`` long option.
- Don't look for a configuration file; only take options via the ``-D`` option.
+.. option:: -C, --isolated
+
+ Don't look for a configuration file; only take options via the :option:`--define` option.
.. versionadded:: 0.5
-.. option:: -D setting=value
+ .. versionchanged:: 7.3
+ Add ``--isolated`` long option.
+
+.. option:: -D setting=value, --define setting=value
Override a configuration value set in the :file:`conf.py` file. The value
must be a number, string, list or dictionary value.
@@ -189,18 +178,27 @@ Options
.. versionchanged:: 1.3
The value can now also be a list value.
-.. option:: -A name=value
+ .. versionchanged:: 7.3
+ Add ``--define`` long option.
+
+.. option:: -A name=value, --html-define name=value
Make the *name* assigned to *value* in the HTML templates.
.. versionadded:: 0.5
-.. option:: -n
+ .. versionchanged:: 7.3
+ Add ``--html-define`` long option.
+
+.. option:: -n, --nitpicky
Run in nit-picky mode. Currently, this generates warnings for all missing
references. See the config value :confval:`nitpick_ignore` for a way to
exclude some references as "known missing".
+ .. versionchanged:: 7.3
+ Add ``--nitpicky`` long option.
+
.. option:: -N, --no-color
Do not emit colored output.
@@ -214,32 +212,51 @@ Options
.. versionadded:: 1.6
-.. option:: -v
+.. option:: -v, --verbose
- Increase verbosity (loglevel). This option can be given up to three times
+ Increase verbosity (log-level). This option can be given up to three times
to get more debug logging output. It implies :option:`-T`.
.. versionadded:: 1.2
-.. option:: -q
+ .. versionchanged:: 7.3
+ Add ``--verbose`` long option.
+
+.. option:: -q, --quiet
Do not output anything on standard output, only write warnings and errors to
standard error.
-.. option:: -Q
+ .. versionchanged:: 7.3
+ Add ``--quiet`` long option.
+
+.. option:: -Q, --silent
Do not output anything on standard output, also suppress warnings. Only
errors are written to standard error.
-.. option:: -w file
+ .. versionchanged:: 7.3
+ Add ``--silent`` long option.
+
+.. option:: -w file, --warning-file file
Write warnings (and errors) to the given file, in addition to standard error.
-.. option:: -W
+ .. versionchanged:: 7.3
+
+ ANSI control sequences are stripped when writing to *file*.
+
+ .. versionchanged:: 7.3
+ Add ``--warning-file`` long option.
+
+.. option:: -W, --fail-on-warning
Turn warnings into errors. This means that the build stops at the first
warning and ``sphinx-build`` exits with exit status 1.
+ .. versionchanged:: 7.3
+ Add ``--fail-on-warning`` long option.
+
.. option:: --keep-going
With -W option, keep going processing when getting warnings to the end
@@ -247,7 +264,7 @@ Options
.. versionadded:: 1.8
-.. option:: -T
+.. option:: -T, --show-traceback
Display the full traceback when an unhandled exception occurs. Otherwise,
only a summary is displayed and the traceback information is saved to a file
@@ -255,11 +272,17 @@ Options
.. versionadded:: 1.2
-.. option:: -P
+ .. versionchanged:: 7.3
+ Add ``--show-traceback`` long option.
+
+.. option:: -P, --pdb
(Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an
unhandled exception occurs while building.
+ .. versionchanged:: 7.3
+ Add ``--pdb`` long option.
+
.. option:: -h, --help, --version
Display usage summary or Sphinx version.