Add longer option names to `sphinx-build` (#11776)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

doc/man/sphinx-build.rst

@@ -64,33 +64,49 @@ Options
 
    .. versionadded:: 1.2.1
 
-.. option:: -b buildername
+.. 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.
 
-.. option:: -a
+   .. 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".
@@ -98,6 +114,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
@@ -114,7 +133,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
@@ -124,13 +143,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.
@@ -149,18 +174,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.
@@ -174,24 +208,33 @@ 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.
 
@@ -199,11 +242,17 @@ Options
 
       ANSI control sequences are stripped when writing to *file*.
 
-.. option:: -W
+   .. 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
@@ -211,7 +260,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
@@ -219,11 +268,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.