Improve CLI documentation for Python discovery options

[pombredanne]

What's the problem this feature will solve?
the --help displayed for the "discovery" is this:

--discovery {builtin} interpreter discovery method (default: builtin)
-p py, --python py interpreter based on what to create environment (path/identifier) - by default use the interpreter where the tool is installed - first found wins (default: [])

I find the help text a little cryptic and I really cannot understand what the --discovery and --python are supposed to be, what I could provide as values and and how to use these.

I see that this has been recently updated with

virtualenv/src/virtualenv/discovery/builtin.py

Line 32 in 7185e57

help="interpreter based on what to create environment (path/identifier) "

but the help could be further improved IMHO

Describe the solution you'd like
We should clarify the help text.

1. for now we should IMHO hide the --discovery option since there is only one way which is builtin, so this is really not an "option". Hiding will help clarify the UI.
2. The --python option help should be improved together with --try-first-with which now seems to overlap with it. I suggest this for a start for --python:

Python interpreter to use to create the environment. This can be either an absolute path to a Python interpreter executable, or an interpreter specification such as "python3.6" to specify Python 3.6 or "39" to specify Python 3.9. Use this option multiple times to provide multiple interpreter. If provided, the first interpreter found that matches a path or specification will be selected. Otherwise, the current interpreter that runs virtualenv is used by default.

The reference to "paths" and "specification" proposed here seems consistent with the code in

virtualenv/src/virtualenv/discovery/builtin.py

Line 18 in 7185e57

self.python_spec = options.python if options.python else [sys.executable]

that defaults to [sys.executable] which is a path string.

In

virtualenv/src/virtualenv/discovery/py_spec.py

Line 29 in 7185e57

def from_string_spec(cls, string_spec):

the spec option seems rather complex which means it is complex to explain and document too. May be it could be simplified?

With that said, the --try-first-with option is now conflicting with the proposed help per

virtualenv/src/virtualenv/discovery/builtin.py

Line 75 in 7185e57

def propose_interpreters(spec, try_first_with, app_data):

... so the suggested help needs to be improved too.

[gaborbernat]

1. for now we should IMHO hide the --discovery option since there is only one way which is builtin, so this is really not an "option". Hiding will help clarify the UI.

I disagree. Users can define new discovery mechanism in plugins, see https://virtualenv.pypa.io/en/latest/extend.html#python-discovery. There might be further ways if the user installs additional plugins.

2. The --python option help should be improved together with --try-first-with which now seems to overlap with it.

It does not. The python is not just an absolute path, it's also any python spec (read https://virtualenv.pypa.io/en/latest/user_guide.html#python-discovery), such as cpython3.8 and then the builtin discovery will go and try to find one that matches that. You can force virtualenv to start the discovery with a given python executable with the --try-first-with (so that you can force a given base python if you have multiple installed on your system that matches it). For example cpython3.8 can match as distributed by Python Core or as distributed by Anaconda.

Python interpreter to use to create the environment. This can be either an absolute path to a Python interpreter executable, or an interpreter specification such as "python3.6" to specify Python 3.6 or "39" to specify Python 3.9. Use this option multiple times to provide multiple interpreter. If provided, the first interpreter found that matches a path or specification will be selected. Otherwise, the current interpreter that runs virtualenv is used by default.

This is way too much to put inside a CLI flag help. It needs to be <20 words.

the spec option seems rather complex which means it is complex to explain and document too. May be it could be simplified?

Not that I'm aware of. Feel free to propose simplifications to it, but note we need to support whatever it supports today.