fix(parser): Fix --discover parsed incorrectly from env

[mimre25]

This PR fixes the parsing of the --discover flag and improves the docs of it to avoid confusion between paths and executables.

The flag was missing the type specification (of_type) and thus parse.get_env_var did not execute the branch for list, but rather for single variables.
The fallback in Converter led to a call to list("abc"), which resulted int a list of characters (["a", "b", "c"]).

• ran the linter to address style issues (tox -e fix)
• wrote descriptive pull request text
• ensured there are test(s) validating the fix
• added news fragment in docs/changelog folder
• updated/extended the documentation

Closes #3272

[mimre25]

@gaborbernat @jugmac00 Right now the changes fix the parsing of the TOX_DISCOVER env variable.

It's important to follow the format described in set-cli-flags-via-environment-variables and separate the list with ; instead of .

However, one thing that I countered is either a confusingly worded documentation or another bug with discover:

--discover PATH - for Python discovery first try the Python executables under these paths (default: [])

emphasis by me

For me this reads as if tox would expect a path (/foo/bar/) under which one or more python executables exist (/foo/bar/python).
However, this is not the case.
Instead tox expects --discover to get one or more python executables (/foo/bar/python).

To illustrate this (using the same project as in the issue):

✗ tox -q -e py310 --discover /home/martin/micromamba/envs/py310/bin/  
  py310: SKIP (0.01 seconds)
  evaluation failed :( (0.08 seconds)                                                                                            [0,28s]
✗ tox -q -e py310 --discover /home/martin/micromamba/envs/py310/bin/python
========================================================= test session starts ==========================================================
platform linux -- Python 3.10.12, pytest-8.1.1, pluggy-1.5.0
cachedir: .tox/py310/.pytest_cache
rootdir: /home/martin/workspace/ansible-lint-empty-lines-between-tasks
configfile: pyproject.toml
testpaths: test
collected 4 items                                                                                                                      

test/test_rule.py ....                                                                                                           [100%]

========================================================== 4 passed in 1.55s ===========================================================
  py310: OK (24.92 seconds)
  congratulations :) (24.99 seconds)     

I propose to rewrite the docs here to be more specific that --discover expects a list of python executables for two reasons:

1. Smaller change 🤓
2. It's backwards compatible, ie, wherever --discover (or $TOX_DISCOVER) is working now, it will continue to work.

What are your thoughts? Should I update the docs?

[gaborbernat]

Yes please.

[mimre25]

@gaborbernat this is ready 🙂