Group CLI arguments in functional groups

[DrGFreeman]

Fixes #305

Replace the primary/secondary argparse argument groups with functional groups:

$ nox -h
usage: nox [-h] [--version] [-l] [-s [SESSIONS [SESSIONS ...]]]
           [-p [PYTHONS [PYTHONS ...]]] [-k KEYWORDS] [-v] [-ts]
           [-db {none,virtualenv,conda,venv}]
           [-fb {none,virtualenv,conda,venv}] [--no-venv] [-r]
           [--no-reuse-existing-virtualenvs] [-R] [-f NOXFILE]
           [--envdir ENVDIR]
           [--extra-pythons [EXTRA_PYTHONS [EXTRA_PYTHONS ...]]]
           [--force-pythons [FORCE_PYTHONS [FORCE_PYTHONS ...]]] [-x]
           [--no-stop-on-first-error] [--error-on-missing-interpreters]
           [--no-error-on-missing-interpreters] [--error-on-external-run]
           [--no-error-on-external-run] [--install-only] [--no-install]
           [--report REPORT] [--non-interactive] [--nocolor] [--forcecolor]
           ...

Nox is a Python automation toolkit.

General arguments:
  These are general arguments used when invoking Nox.

  -h, --help            Show this help message and exit.
  --version             Show the Nox version and exit.
  posargs               Arguments following ``--`` that are passed through to
                        the session(s).
  -f NOXFILE, --noxfile NOXFILE
                        Location of the Python file containing nox sessions.

Sessions arguments & flags:
  These arguments are used to control which Nox session(s) to execute.

  -l, --list-sessions, --list
                        List all available sessions and exit.
  -s [SESSIONS [SESSIONS ...]], -e [SESSIONS [SESSIONS ...]], --sessions [SESSIONS [SESSIONS ...]], --session [SESSIONS [SESSIONS ...]]
                        Which sessions to run. By default, all sessions will
                        run.
  -k KEYWORDS, --keywords KEYWORDS
                        Only run sessions that match the given expression.

Python arguments & flags:
  These arguments are used to control which Python version(s) to use.

  -p [PYTHONS [PYTHONS ...]], --pythons [PYTHONS [PYTHONS ...]], --python [PYTHONS [PYTHONS ...]]
                        Only run sessions that use the given python
                        interpreter versions.
  --extra-pythons [EXTRA_PYTHONS [EXTRA_PYTHONS ...]], --extra-python [EXTRA_PYTHONS [EXTRA_PYTHONS ...]]
                        Additionally, run sessions using the given python
                        interpreter versions.
  --force-pythons [FORCE_PYTHONS [FORCE_PYTHONS ...]], --force-python [FORCE_PYTHONS [FORCE_PYTHONS ...]]
                        Run sessions with the given interpreters instead of
                        those listed in the Noxfile. This is a shorthand for
                        ``--python=X.Y --extra-python=X.Y``.

Environment arguments & flags:
  These arguments are used to control Nox's creation and usage of virtual
  environments.

  -db {none,virtualenv,conda,venv}, --default-venv-backend {none,virtualenv,conda,venv}
                        Virtual environment backend to use by default for nox
                        sessions, this is ``'virtualenv'`` by default but any
                        of ``('virtualenv', 'conda', 'venv')`` are accepted.
  -fb {none,virtualenv,conda,venv}, --force-venv-backend {none,virtualenv,conda,venv}
                        Virtual environment backend to force-use for all nox
                        sessions in this run, overriding any other venv
                        backend declared in the nox file and ignoring the
                        default backend. Any of ``('virtualenv', 'conda',
                        'venv')`` are accepted.
  --no-venv             Runs the selected sessions directly on the current
                        interpreter, without creating a venv. This is an alias
                        for '--force-venv-backend none'.
  -r, --reuse-existing-virtualenvs
                        Re-use existing virtualenvs instead of recreating
                        them.
  --no-reuse-existing-virtualenvs
                        Disables --reuse-existing-virtualenvs if it is enabled
                        in the Noxfile.
  -R                    Re-use existing virtualenvs and skip package re-
                        installation. This is an alias for '--reuse-existing-
                        virtualenvs --no-install'.
  --envdir ENVDIR       Directory where nox will store virtualenvs, this is
                        ``.nox`` by default.

Execution arguments & flags:
  These arguments are used to control execution of sessions.

  -x, --stop-on-first-error
                        Stop after the first error.
  --no-stop-on-first-error
                        Disables --stop-on-first-error if it is enabled in the
                        Noxfile.
  --error-on-missing-interpreters
                        Error instead of skipping sessions if an interpreter
                        can not be located.
  --no-error-on-missing-interpreters
                        Disables --error-on-missing-interpreters if it is
                        enabled in the Noxfile.
  --error-on-external-run
                        Error if run() is used to execute a program that isn't
                        installed in a session's virtualenv.
  --no-error-on-external-run
                        Disables --error-on-external-run if it is enabled in
                        the Noxfile.
  --install-only        Skip session.run invocations in the Noxfile.
  --no-install          Skip invocations of session methods for installing
                        packages (session.install, session.conda_install,
                        session.run_always) when a virtualenv is being reused.

Reporting arguments & flags:
  These arguments are used to control Nox's reporting during execution.

  -v, --verbose         Logs the output of all commands run including commands
                        marked silent.
  -ts, --add-timestamp  Adds a timestamp to logged output.
  --report REPORT       Output a report of all sessions to the given filename.
  --non-interactive     Force session.interactive to always be False, even in
                        interactive sessions.
  --nocolor, --no-color
                        Disable all color output.
  --forcecolor, --force-color
                        Force color output, even if stdout is not an
                        interactive terminal.

This is a first pass, I'm open for comments & suggestions on the arguments grouping, group naming and descriptions.

[cjolowicz]

I like the way you grouped the options, it greatly improves the readability of --help! Thanks :)

It looks like the tests need to be adapted. Let us know if you need any pointers with this.

Two minor, somewhat subjective, points:

• Should we move --non-interactive into the execution group? It's commonly used to select a different code path when in CI. By itself, it does not change Nox's operation or reporting, it's up to the session function to decide what to do with it.
• Should we shorten "arguments & flags" to just "arguments" (or "options")?

[DrGFreeman]

Thanks for the feedback @cjolowicz!

It looks like the tests need to be adapted. Let us know if you need any pointers with this.

This should fixed by 8627404, I had non-committed changes when I ran the tests locally 😓

• Should we move --non-interactive into the execution group? It's commonly used to select a different code path when in CI. By itself, it does not change Nox's operation or reporting, it's up to the session function to decide what to do with it.

Makes sense, I'm not yet fully familiar with the project so I thought had more to do with verbosity. I will make the change later today.

• Should we shorten "arguments & flags" to just "arguments" (or "options")?

Just to confirm, I would change it only in the group title, not in the group description? e.g.:

Sessions options:
  These arguments are used to control which Nox session(s) to execute.

[theacodes]

This looks great, I'm happy with it once @cjolowicz is. :)

[cjolowicz]

All tests are passing now.

My suggestions are really optional, and just the group titles are enough. If you find time to do this later, great, otherwise I'm happy for this to be merged as-is.

[DrGFreeman]

@cjolowicz, I moved --non-interactive into the execution group and shortened the display names as per your suggestion. I also rebased the branch to main.

You can merge if you are satisfied with the changes.

Thx.

[cjolowicz]

Thanks!