diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 654a851ec53..f5c373620b8 100644 --- a/doc/man/sphinx-build.rst +++ b/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. diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py index 9f31ffe72be..809ee076032 100644 --- a/sphinx/cmd/build.py +++ b/sphinx/cmd/build.py @@ -149,16 +149,16 @@ 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, @@ -166,30 +166,30 @@ def get_parser() -> argparse.ArgumentParser: 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