-
Notifications
You must be signed in to change notification settings - Fork 2k
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.
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
Add full-length versions of CLI flags #11776
Changes from 1 commit
d4e7225
8908f5c
5666e46
f7bd49e
a2cf330
cd91734
68f26d6
8653aec
f35570a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -64,40 +64,55 @@ 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, --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 | ||
.. versionchanged:: 7.3 | ||
Add ``--all`` long option. | ||
|
||
.. option:: -E, --no-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 ``--no-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 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`` long option. | ||
|
||
.. option:: -j N, --jobs N | ||
|
||
Distribute the build over *N* processes in parallel, to make building on | ||
|
@@ -114,7 +129,7 @@ Options | |
.. versionchanged:: 6.2 | ||
Add ``--jobs`` long option. | ||
|
||
.. option:: -c path | ||
.. option:: -c path, --config 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,12 +139,18 @@ Options | |
|
||
.. versionadded:: 0.3 | ||
|
||
.. option:: -C | ||
.. versionchanged:: 7.3 | ||
Add ``--config`` long option. | ||
|
||
.. option:: -C, --no-config | ||
|
||
Don't look for a configuration file; only take options via the ``-D`` option. | ||
|
||
.. versionadded:: 0.5 | ||
|
||
.. versionchanged:: 7.3 | ||
Add ``--no-config`` long option. | ||
|
||
.. option:: -D setting=value | ||
|
||
Override a configuration value set in the :file:`conf.py` file. The value | ||
|
@@ -155,12 +176,15 @@ Options | |
|
||
.. versionadded:: 0.5 | ||
|
||
.. option:: -n | ||
.. option:: -n, --nit-picky | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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 ``--nit-picky`` long option. | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. option:: -N, --no-color | ||
|
||
Do not emit colored output. | ||
|
@@ -174,56 +198,77 @@ Options | |
|
||
.. versionadded:: 1.6 | ||
|
||
.. option:: -v | ||
.. option:: -v, --verbose | ||
|
||
Increase verbosity (loglevel). This option can be given up to three times | ||
to get more debug logging output. It implies :option:`-T`. | ||
|
||
.. versionadded:: 1.2 | ||
|
||
.. option:: -q | ||
.. 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, --really-quiet | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Do not output anything on standard output, also suppress warnings. Only | ||
errors are written to standard error. | ||
|
||
.. option:: -w file | ||
.. versionchanged:: 7.3 | ||
Add ``--really-quiet`` long option. | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. option:: -w file, --write 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 ``--write`` long option. | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. option:: -W, --errors | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Would There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm, this option is often used in combination with:
My thinking was these might go together:
And
Open to other suggestions! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If possible, I would have suggested There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I prefer There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I usually try to come with flags that are used by other well-known tools because it makes less options to remember overall, but I think yours is a bit betetr when used with
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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 ``--errors`` long option. | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. 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 | ||
.. versionchanged:: 7.3 | ||
Add ``--keep-going`` long option. | ||
|
||
.. option:: -T, --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 ``--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 ``--pdf`` long option. | ||
hugovk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. option:: -h, --help, --version | ||
|
||
Display usage summary or Sphinx version. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe
--isolate
or--no-incremental
to mimick Python/mypy options (I think--no-incremental
is more correct since--isolate
may assume not looking for the configuration file).There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ruff has
--isolated
to ignore config:Mypy has
--no-incremental
to disable the cacge:I couldn't find similar Python options.
Mypy's
--no-incremental
seems closer, will update to use that 👍There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fot Python it's
-I
for "isolated".