Skip to content

Add full-length versions of CLI flags #11776

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

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 3 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.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 60 additions & 15 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,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
Copy link
Member

@picnixz picnixz Dec 24, 2023

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).

Copy link
Contributor Author

@hugovk hugovk Dec 24, 2023

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:

      --isolated
          Ignore all configuration files

Mypy has --no-incremental to disable the cacge:

Incremental mode:
  Adjust how mypy incrementally type checks and caches modules. Mypy caches type information about modules into a cache to let you speed up future
  invocations of mypy. Also see mypy's daemon mode: mypy.readthedocs.io/en/stable/mypy_daemon.html#mypy-daemon

  --no-incremental          Disable module cache (inverse: --incremental)

I couldn't find similar Python options.

Mypy's --no-incremental seems closer, will update to use that 👍

Copy link
Member

@picnixz picnixz Dec 24, 2023

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".


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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -155,12 +176,15 @@ Options

.. versionadded:: 0.5

.. option:: -n
.. option:: -n, --nit-picky

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.

.. option:: -N, --no-color

Do not emit colored output.
Expand All @@ -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
.. 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, --really-quiet

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.

.. 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.

.. option:: -W, --errors
Copy link
Contributor

@ezio-melotti ezio-melotti Nov 29, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would --fail-fast be a better name than --errors?
I don't find --errors particularly descriptive.

Copy link
Contributor Author

@hugovk hugovk Nov 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, this option is often used in combination with:

  --keep-going          with -W, keep going when getting warnings

My thinking was these might go together:

--errors --keep-going

And --fail-fast would seem to contradict it:

--fail-fast --keep-going

Open to other suggestions!

Copy link
Member

@picnixz picnixz Dec 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If possible, I would have suggested --fatal-warnings because it's exactly what it does for gcc. Or we can go for --warning-is-error or --warn-as-error (but I would prefer the former).

Copy link
Member

@AA-Turner AA-Turner Dec 26, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer --fail-on-warning here, it's more descriptive, if a little wordier.

Copy link
Member

@picnixz picnixz Dec 26, 2023

Choose a reason for hiding this comment

The 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 --keep-going


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.

.. 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, --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 ``--pdb`` long option.

.. option:: -h, --help, --version

Display usage summary or Sphinx version.
Expand Down
30 changes: 15 additions & 15 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', '--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', '--no-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', 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', 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', '--no-config', action='store_true', dest='noconfig',
help=__('use no config file at all, only -D options'))
group.add_argument('-D', metavar='setting=value', action='append',
dest='define', default=[],
help=__('override a setting in configuration file'))
group.add_argument('-A', 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', '--nit-picky', 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', '--really-quiet', 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', '--write', 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', '--errors', 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', '--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