Add full-length versions of CLI flags

doc/man/sphinx-build.rst

@@ -74,23 +74,27 @@ Options
    .. versionchanged:: 7.3
       Add ``--builder`` long option.
 
-.. option:: -a, --all
+.. 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 :option:`fresh-env` instead.
+
    .. versionchanged:: 7.3
-      Add ``--all`` long option.
+      Add ``--write-all`` long option.
 
-.. option:: -E, --incremental
+.. 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.
 
    .. versionchanged:: 7.3
-      Add ``--incremental`` long option.
+      Add ``--fresh-env`` long option.
 
 .. option:: -t tag, --tag tag
 
@@ -102,7 +106,7 @@ Options
    .. versionchanged:: 7.3
       Add ``--tag`` long option.
 
-.. option:: -d path, --doctree path
+.. 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".
@@ -111,7 +115,7 @@ Options
    directory (the doctrees can be shared between all builders).
 
    .. versionchanged:: 7.3
-      Add ``--doctree`` long option.
+      Add ``--doctree-dir`` long option.
 
 .. option:: -j N, --jobs N
 
@@ -129,7 +133,7 @@ Options
    .. versionchanged:: 6.2
       Add ``--jobs`` long option.
 
-.. option:: -c path, --config 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
@@ -140,16 +144,16 @@ Options
    .. versionadded:: 0.3
 
    .. versionchanged:: 7.3
-      Add ``--config`` long option.
+      Add ``--config-dir`` long option.
 
-.. option:: -C, --no-config
+.. option:: -C, --isolated
 
-   Don't look for a configuration file; only take options via the ``-D`` option.
+   Don't look for a configuration file; only take options via the :option:`--define` option.
 
    .. versionadded:: 0.5
 
    .. versionchanged:: 7.3
-      Add ``--no-config`` long option.
+      Add ``--isolated`` long option.
 
 .. option:: -D setting=value, --define setting=value
 
@@ -173,14 +177,14 @@ Options
    .. versionchanged:: 7.3
       Add ``--define`` long option.
 
-.. option:: -A name=value, --html-var name=value
+.. option:: -A name=value, --html-define name=value
 
    Make the *name* assigned to *value* in the HTML templates.
 
    .. versionadded:: 0.5
 
    .. versionchanged:: 7.3
-      Add ``--html-var`` long option.
+      Add ``--html-define`` long option.
 
 .. option:: -n, --nitpicky
 
@@ -206,7 +210,7 @@ Options
 
 .. 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
@@ -230,7 +234,7 @@ Options
    .. versionchanged:: 7.3
       Add ``--silent`` long option.
 
-.. option:: -w file, --write file
+.. option:: -w file, --warning-file file
 
    Write warnings (and errors) to the given file, in addition to standard error.
 
@@ -241,7 +245,7 @@ Options
    .. versionchanged:: 7.3
       Add ``--write`` long option.
 
-.. option:: -W, --fatal-warnings
+.. 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.
@@ -256,7 +260,7 @@ Options
 
    .. versionadded:: 1.8
 
-.. option:: -T, --traceback
+.. 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

sphinx/cmd/build.py

@@ -152,29 +152,29 @@ def get_parser() -> argparse.ArgumentParser:
     group.add_argument('-b', '--builder', metavar='BUILDER', dest='builder',
                        default='html',
                        help=__('builder to use (default: html)'))
-    group.add_argument('-a', '--all', 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', '--incremental', 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', '--doctree', 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', '--config', 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', '--no-config', 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', '--define', metavar='setting=value', action='append',
                        dest='define', default=[],
                        help=__('override a setting in configuration file'))
-    group.add_argument('-A', '--html-var', 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', '--tag', metavar='TAG', action='append',