mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
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>
This commit is contained in:
Hugo van Kemenade
GitHub
parent
ab70ef73a8
commit
aea69ea6af
@ -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.
|
||||
|
||||
@ -149,16 +149,16 @@ files can be built by specifying individual filenames.
|
||||
'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 @@ files can be built by specifying individual filenames.
|
||||
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 @@ files can be built by specifying individual filenames.
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user