Restructuring pip-tools docs gradually into sections

[sirosen]

When I look at the pip-tools docs, I'm struck by the fact that everything is in one large page. It's good for some things (Ctrl+F) but bad for others (too long to read, hard to browse). I think we would benefit from a bit of refactoring so that we have multiple pages and sections.

This comes up in cases like this one, where I'd rather not add to the big readme until we have some clearer plan for how docs get laid out. Relatedly, some topics are not covered in enough depth, and I suspect this is a consequence of having everything on a single page.

I also think it's useful to have a strategy that allows us to approach this change in a steady, incremental way. It's easier to review small changes, and the first goal is to break the pattern that everything has to go into the readme. Once that's done, moving bits here and there should be easier.

I'm looking at the readme now to try to pick one first topic to make into a new page. Some things could be fleshed out a great deal more. Others are maybe fine as-is, but would be more legible in separate pages. I think it's best to start with something where we get immediate benefit from moving to a separate page because we can cover the topic in greater depth.

Initial candidates:

• cross-environment resolution can expand to cover script examples and note that running on multiple Pythons may not be sufficient (e.g., platform specific markers)
• version control integration is, IMO, incorrectly named, and instead belongs on a page about "pre-commit usage". It should also touch on the fact that the output is used as constraints data during resolution, so these hooks should be relatively stable. And it should warn about the downsides of a hook which requires the network (slow, potentially unstable, won't work in pre-commit.ci).
• configuration is very commonly a dedicated page. It could be expanded with all of the various options. It currently just says "all CLI arguments" with a link which works in sphinx but is broken in GitHub and PyPI, which I do not think is sufficiently informative to be a useful reference.

I think step 1 is to move one of these, with absolutely minimal changes to content (corrections and handling the move only). The first will be the most consequential, since its placement and naming will influence the rest. On review, I'm inclined to pick up configuration and move it to a page titled Configuration (keep it simple!).

@webknjaz, do you have strong opinions about this as an overall project, or about which of the above (or some other) section should be picked out first?

[webknjaz]

Fully agree. Personally, the cross-env problem is close to heart but is also a rather triggering topic... Between a lot of explaining needed all the time (#826) and DIY solutions I end up deploying, it's a rather important topic. But I don't mind you starting wherever you like.

On a related note, we should strive to make use of the https://diataxis.fr [amework] and maybe also look into https://vale.sh.

[webknjaz]

I learned of https://kdeldycke.github.io/click-extra/sphinx.html recently. Maybe, it'll be useful too.