Is there room to improve options documentation?

[ucodery]

The Options page in the documentation seems especially difficult to decipher. Part of this is likely to be because it is generated, as it probably should be at this size. But all the examples, if they can be quite called that, are overly-vague.

When recently setting up a new project I had to go through several iterations of guessing what py_version was expecting, it says the default is py3 but also says that 38 is the current value (this looks like a small piece of the build environment escaping into the project?) As a side note the CLI help seems a bit more straightforward on acceptable values to this particular option. I'm still not sure the exact structure of a valid version string is to this field.

Also, showing the default value for a setting isn't always the most useful piece of information. Seems like most of these are frozenset() but what can go in that frozen set? And what is a frozenset in toml - presumably an array; in cfg?
python != toml so displaying defaults in python repr like False don't translate well to writing a config file as only false will work in pyproject.toml.

I realize this is a big effort ask, maybe requiring multiple PRs but if there is interest I would be willing to devote time to this issue.

PS a big kudos to keeping such detailed documentation on this complex a project (html + md is around half the project and almost 1:1 python LoC! 🙌 📖 )

[timothycrosley]

Hi @ucodery,

I agree there is a lot of room for improvement here - especially in regards to the option documentation. It is auto generated from the CLI help strings, perhaps the auto generator could provide a way to neatly supplant that auto included information with more details in particular examples? In any case excited for improvements in this area, and would happily approve PRs here!

When recently setting up a new project I had to go through several iterations of guessing what py_version was expecting, it says the default is py3 but also says that 38 is the current value (this looks like a small piece of the build environment escaping into the project?) As a side note the CLI help seems a bit more straightforward on acceptable values to this particular option. I'm still not sure the exact structure of a valid version string is to this field.`

You're exactly right that the 38 is a leak of the Python environment used to auto generate that part of the documentation. py3 is indeed the default (which is assuming that any version of Python3 could be the target) py38 would only be used if the version was set to auto --py auto. The correct value is either the string all or auto or version target: 2,27,3,35,36,37,38,39 example: --py all to target all supported versions or --py 39 to target explicitly python3.9 only.

Also, showing the default value for a setting isn't always the most useful piece of information. Seems like most of these are frozenset() but what can go in that frozen set? And what is a frozenset in toml - presumably an array; in cfg?
python != toml so displaying defaults in python repr like False don't translate well to writing a config file as only false will work in pyproject.toml.

This is certainly far from ideal. I suppose with an updated docs page, in an ideal world, we would show examples across the CLI, API, and config file.

Needless to say, excited to see any work in this area, and happy to help in any way I can!

[drjasonharrison]

The documentation for

• src_paths is type tuple but pyproject.toml expects a list of strings: ["one.py", "two.py"]
• skip_glob is type frozenset but pyproject.toml expects a list of strings: `["dist", "build"]

Example pyproject.toml files with non-minimal tools.isort sections:

• https://github.com/Pylons/pyramid/blob/master/pyproject.toml
• http://www.legendu.net/misc/blog/sort-python-imports-using-isort
• https://github.com/python-poetry/poetry/blob/master/pyproject.toml
• https://github.com/Gr1N/nats-python/blob/master/pyproject.toml

by combining as many of the above as possible, this is an incomplete but most of the settings:

atomic = true
combine_as_imports = true
ensure_newline_before_comments = true
filter_files = true
force_grid_wrap = 0
force_single_line = true
include_trailing_comma = true
indent = "    "
known_first_party = "poetry"
line_length = 100
lines_after_imports = 2
lines_between_types = 1
multi_line_output = 3
profile = "black"
sections = "FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER"
skip = ".eggs,.tox,venv,.venv"
skip_glob = ["*/setup.py", "external/*"]
src_paths = ["poetry", "tests"]
use_parentheses = true

[timothycrosley]

While there is always room for improvement, I think all the major pain points listed in this issue have now been addressed. Thanks for the great suggestions for improvement!

[ucodery]

Wow, these new example fields are so good! Makes it easy to copy/paste most of the way to new behavior.