General docs improvements for v3.0

[joerick]

I think a bit of organisation / rethinking is due. The main change I've made here so far is to the navigation - it now looks like this:

I decided to go for the tree-based approach because it deals better with many sections/pages.

We can make the change to pyproject.toml-style configuration in this PR too, if you like @henryiii .

[henryiii]

We don't have to swap the envvar / TOML config in this PR, it can be a followup, but it is on the planned items for 3.0.

Also, I know I was considering making cibuildwheel.toml a supported filename around the time we added the schema (since I had to set a filename for SchemaStore), maybe we could look into doing that for 3.0. Might help encourage TOML usage.

[henryiii]

I can work on the toml/envvar swap once this is done.

[joerick]

Okay, I'll try to tie up these changes soon.

Also, I know I was considering making cibuildwheel.toml a supported filename around the time we added the schema (since I had to set a filename for SchemaStore), maybe we could look into doing that for 3.0. Might help encourage TOML usage.

You mean a file that's auto-detected at the project root? Personally I'm not a fan of extra project root files but I can see that some might prefer it. But, I do like the shorthand of "pyproject.toml" in tab labels and such. Diluting that to "TOML" might make it less friendly to new users.

[joerick]

This should be ready for a review. I've made quite a few changes, mostly to organisation, but where I inevitably spot things that are inaccurate or out-of-date I've fixed them too, so there's quite a bit in this diff.

Probably the easiest thing is to view the rendered version.

Big things:

• Moved the platforms pages into a single page, and grouped together FAQ entries here. The platform-specific information is very useful, but having them as separate pages took a lot of space in the top-level of the navbar. Also, grouping platform specific information like this is much better than scattering it around the docs, so I've moved a few FAQ entries into this page, too.
• Split out the CI services setup into its own page. It always felt strange that the CI configs were pushed down below the running locally section, and, I think it's good to have a page in the navbar with 'CI services', as a lot of people are just looking for copy/paste examples.
• Split out the configuration methods into their own page, separate from the options docs. This lets the options page load into the TOC, which is a much better experience.
• A general tidy up of the 'Tips & tricks' page.

[joerick]

This info moved to platforms.md.

[henryiii]

Should we update the for 3.0, now that {project}/ isn't needed, but test-sources might be?

[joerick]

Yeah, good idea on removing {project}. I think we don't need TEST_SOURCES though? It's more of a thing that can be discovered as/when it's needed?