Improve documentation for configuration options

[JelleZijlstra]

Currently, our config options are documented only in a collapsed-by-default text block in https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#command-line-options. This is not very discoverable and makes it hard to give more detailed documentation, such as examples.

Instead, we should have a docs page with a separate section for each option. We can start with the existing descriptions, and extend them as needed for options with more complicated behavior.

[billytetrud]

I completely missed the collapsed CLI reference. This makes the documentation really difficult to use as a reference unless you already know where to find the info.

I noticed further down it says "You’ve probably noted that not all of the options you can pass to Black have been covered. Don’t worry, the rest will be covered in a later section." I don't see any obvious "later section" where these things are covered. Also, if you're going to say that, please link to what later section you're talking about. Devs don't generally read documentation from cover to cover, so its really unhelpful to assume that they'll get to it in some unspecified later section of the docs.

[ichard26]

Yup, yup, I understand (you can blame me for these poor documentation decisions), we're planning to make the usage and configuration pages a lot more reference-like cutting down on the tutorial-ish aspect of it (as they could live in the guides/ section). Thanks for the earnest feedback!

[jacalata]

This might be a good place to ask how or if I can set the src in pyproject.toml, or, as the docs say

A good next step would be configuring auto-discovery so black . is all you need instead of laborously listing every file or directory. You can get started by heading over to File collection and discovery.

black . is ok, but is there a way to set the config so I get the equivalent of black src other-folder by just typing black?

[ichard26]

Currently no, there is an open proposal for this, GH-861, but it's unlikely to be accepted.