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

Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: Bénédikt Tran <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

Author: 4 people

doc/man/sphinx-build.rst

@@ -64,40 +64,59 @@ 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".
    Normally, these files are put in a directory called :file:`.doctrees` under
    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,56 +208,77 @@ 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.
 
    .. versionchanged:: 7.3
 
       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
    of build, and ``sphinx-build`` exits with exit status 1.
 
    .. 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
    for further analysis.
 
    .. 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.

sphinx/cmd/build.py

@@ -149,47 +149,47 @@ def get_parser() -> argparse.ArgumentParser:
                                 'if -a is specified'))
 
     group = parser.add_argument_group(__('general options'))
-    group.add_argument('-b', metavar='BUILDER', dest='builder',
+    group.add_argument('-b', '--builder', metavar='BUILDER', dest='builder',
                        default='html',
                        help=__('builder to use (default: html)'))
-    group.add_argument('-a', action='store_true', dest='force_all',
+    group.add_argument('-a', '--write-all', action='store_true', dest='force_all',
                        help=__('write all files (default: only write new and '
                                'changed files)'))
-    group.add_argument('-E', action='store_true', dest='freshenv',
+    group.add_argument('-E', '--fresh-env', action='store_true', dest='freshenv',
                        help=__("don't use a saved environment, always read "
                                'all files'))
-    group.add_argument('-d', metavar='PATH', dest='doctreedir',
+    group.add_argument('-d', '--doctree-dir', metavar='PATH', dest='doctreedir',
                        help=__('path for the cached environment and doctree '
                                'files (default: OUTPUTDIR/.doctrees)'))
     group.add_argument('-j', '--jobs', metavar='N', default=1, type=jobs_argument,
                        dest='jobs',
                        help=__('build in parallel with N processes where '
                                'possible (special value "auto" will set N to cpu-count)'))
     group = parser.add_argument_group('build configuration options')
-    group.add_argument('-c', metavar='PATH', dest='confdir',
+    group.add_argument('-c', '--config-dir', metavar='PATH', dest='confdir',
                        help=__('path where configuration file (conf.py) is '
                                'located (default: same as SOURCEDIR)'))
-    group.add_argument('-C', action='store_true', dest='noconfig',
+    group.add_argument('-C', '--isolated', action='store_true', dest='noconfig',
                        help=__('use no config file at all, only -D options'))
-    group.add_argument('-D', metavar='setting=value', action='append',
+    group.add_argument('-D', '--define', metavar='setting=value', action='append',
                        dest='define', default=[],
                        help=__('override a setting in configuration file'))
-    group.add_argument('-A', metavar='name=value', action='append',
+    group.add_argument('-A', '--html-define', metavar='name=value', action='append',
                        dest='htmldefine', default=[],
                        help=__('pass a value into HTML templates'))
-    group.add_argument('-t', metavar='TAG', action='append',
+    group.add_argument('-t', '--tag', metavar='TAG', action='append',
                        dest='tags', default=[],
                        help=__('define tag: include "only" blocks with TAG'))
-    group.add_argument('-n', action='store_true', dest='nitpicky',
+    group.add_argument('-n', '--nitpicky', action='store_true', dest='nitpicky',
                        help=__('nit-picky mode, warn about all missing '
                                'references'))
 
     group = parser.add_argument_group(__('console output options'))
-    group.add_argument('-v', action='count', dest='verbosity', default=0,
+    group.add_argument('-v', '--verbose', action='count', dest='verbosity', default=0,
                        help=__('increase verbosity (can be repeated)'))
-    group.add_argument('-q', action='store_true', dest='quiet',
+    group.add_argument('-q', '--quiet', action='store_true', dest='quiet',
                        help=__('no output on stdout, just warnings on stderr'))
-    group.add_argument('-Q', action='store_true', dest='really_quiet',
+    group.add_argument('-Q', '--silent', action='store_true', dest='really_quiet',
                        help=__('no output at all, not even warnings'))
     group.add_argument('--color', action='store_const', const='yes',
                        default='auto',
@@ -198,15 +198,15 @@ def get_parser() -> argparse.ArgumentParser:
                        const='no',
                        help=__('do not emit colored output (default: '
                                'auto-detect)'))
-    group.add_argument('-w', metavar='FILE', dest='warnfile',
+    group.add_argument('-w', '--warning-file', metavar='FILE', dest='warnfile',
                        help=__('write warnings (and errors) to given file'))
-    group.add_argument('-W', action='store_true', dest='warningiserror',
+    group.add_argument('-W', '--fail-on-warning', action='store_true', dest='warningiserror',
                        help=__('turn warnings into errors'))
     group.add_argument('--keep-going', action='store_true', dest='keep_going',
                        help=__("with -W, keep going when getting warnings"))
-    group.add_argument('-T', action='store_true', dest='traceback',
+    group.add_argument('-T', '--show-traceback', action='store_true', dest='traceback',
                        help=__('show full traceback on exception'))
-    group.add_argument('-P', action='store_true', dest='pdb',
+    group.add_argument('-P', '--pdb', action='store_true', dest='pdb',
                        help=__('run Pdb on exception'))
 
     return parser