Add full-length versions of CLI flags

[hugovk]

Feature or Bugfix

• Feature

Purpose

• Improve usability of sphinx-build

Detail

• I find it very difficult to remember what the single letter command-line arguments are for sphinx-build and often have to re-look them up via --help
• I usually use sphinx-build via a Makfile, and long options are just fine there, and better at self-documenting
• Long options are a CLI best practice, see Command Line Interface Guidelines

Have full-length versions of all flags. For example, have both -h and --help. Having the full version is useful in scripts where you want to be verbose and descriptive, and you don’t have to look up the meaning of flags everywhere.

• And GNU Coding Standards:

Please define long-named options that are equivalent to the single-letter Unix-style options. We hope to make GNU more user friendly this way.

---

I didn't add any for these two because I wasn't sure what their long versions could be:

• -D setting=value
• -A name=value

Relates

• Make --jobs a synonym for -j #11210 added --jobs

[ezio-melotti]

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

[hugovk]

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!

[picnixz]

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

[AA-Turner]

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

[picnixz]

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

[picnixz]

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

[hugovk]

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 👍

[picnixz]

Fot Python it's -I for "isolated".

[picnixz]

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

[picnixz]

Btw for the -D it's simply --define and for the -A I think it should be something like --var=... or --html-var or --jinja-var since it's for templates only iirc.

[AA-Turner]

An alternate suggestion for -D would be --config-override, to be more descriptive that the option is intended to override settings in the configuration file.

A