docs: flip TOML and envvars order

[henryiii]

To start, I've asked Copilot for a script to flip the order of the tabs. It gave me this one:

import re

# filepath: /Users/henryschreiner/git/software/cibuildwheel/docs/options.md
file_path = "/Users/henryschreiner/git/software/cibuildwheel/docs/options.md"

# Regular expression to match the examples section
example_pattern = re.compile(
    r"(!!! tab examples \"Environment variables\".*?```.*?```.*?)"
    r"(!!! tab examples \"pyproject\.toml\".*?```.*?```.*?)",
    re.DOTALL
)

def flip_examples(file_path):
    with open(file_path, "r") as file:
        content = file.read()

    # Swap the order of the examples
    updated_content = example_pattern.sub(r"\2\n\n\1", content)

    with open(file_path, "w") as file:
        file.write(updated_content)

    print("Examples flipped successfully!")

# Run the function
flip_examples(file_path)

This commit is the result of that.

---

Next I'd like to update the headings so that both options are shown. I'd like to put one on the left, the other on the right, but not sure how to do that yet. Putting this here for now.

[joerick]

I added some code to make little tags like this on each option

They work by adding attributes using markdown attribute list syntax, like so:

### `archs` {: #archs cmd-line env-var toml }

[joerick]

But, I did notice a problem with the result of the swapping code, it seems that some of the tabs got out-of-sync in the swap - here the examples for project-requires-python and enable got mixed up.

[henryiii]

I was secretly hoping you would jump in and fix this, though this is even better than what I was imagining. :)

[joerick]

I've only flipped the titles and added attrs for the first few headings, but thought I'd push where I was up to.

[henryiii]

I can fix this if you want, but at PyCon, so might not be soon. (Probably tonight Sunday night or next week)

[henryiii]

Fixed a few small things too, like the old mention of numpy needing to be old (not true since some 2.x version), and the text on enable.

[henryiii]

The table at the top seems to be picking up the last section and sections, though they aren't options. It's kind of handy, but noticed the current docs don't do that.

[henryiii]

By the way, the badges align a little strangely when the window is narrow. Not terrible.

I think this is ready.

[joerick]

By the way, the badges align a little strangely when the window is narrow. Not terrible.

Yeah, I noticed that too. I can fix it when I get half an hour to play in detail.

[joerick]

A few things I noticed when looking though just now. Most are styling-related, which I can deal with.

• the two ALL_CAPS options jump out like a sore thumb, I think we should just normalise the header naming to kebab-case, the badge handles the specifics
• The sidebar TOC is missing a few sections

• This formatting of 'command-line' section in the top-of-page TOC is a bit janky

• this formatting of badges is odd due to the use of float. I'll switch to a flexbox container.

• the env var badge for this entry is missing a CIBW_

(while i'm at it)

• this table (build+skip) formatting is terrible with the line-breaks inside each identifier