Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add full-length versions of CLI flags #11776

Merged
merged 9 commits into from
Dec 27, 2023
Merged

Add full-length versions of CLI flags #11776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d4e7225
Add full-length versions of CLI flags
hugovk Nov 28, 2023
8908f5c
--pdb not --pdf
hugovk Nov 29, 2023
5666e46
Update options help
hugovk Nov 29, 2023
f7bd49e
Update long options
hugovk Dec 24, 2023
a2cf330
Update long options
hugovk Dec 24, 2023
cd91734
Merge branch 'master' into add--long-options
AA-Turner Dec 26, 2023
68f26d6
Renaming
AA-Turner Dec 26, 2023
8653aec
syntactical error
AA-Turner Dec 26, 2023
f35570a
Mopping up
AA-Turner Dec 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
93 changes: 74 additions & 19 deletions doc/man/sphinx-build.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down
34 changes: 17 additions & 17 deletions sphinx/cmd/build.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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
Expand Down