Adding upstream version 7.3.7.upstream/7.3.7

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.