docs: cleanup

[henryiii]

Adding three things (one commit each):

• Support for [docs] and [test] extras, allowing these to be installed individually. Dev no longer includes the docs requirements (but the requirements-dev file does both for you, just like before). Simplifies RtD build a little bit. Bumped the pinned versions of docs requirements. Edit: [test] not [tests], more common (checked Pandas).
• Bump to showing the 20.04 images, since the default should be changing soon. (GHA only, not sure about Azure or others)
• Support nested markdown in other constructs. @joerick I think there might be one other place where this was needed? Removed for now, might be ruining styling

[joerick]

Something seems to have gone wrong with our styling, here...

Before	After

[joerick]

This seems a little odd - shouldn't requirements-dev match [dev]? and [dev] include the requirements for building docs? Could the [dev] extra depend on other extras?

[henryiii]

Extras can't depend on other extras (my biggest pet peeve - and one that Poetry seems to not have solved when they built a more complicated requirements system), so they'd have to be listed twice. However, this means there might something missing from docs. I thought it was a little nicer to split "docs" from "dev", as often developers are not rebuilding the docs, so it gives more freedom there (since it's easy to ask for multiple extras. You can't as easily make multiple requirements files (it's ugly), and for historical purposes, the requirements-dev should stay the same. But I can also list them twice if better.

[henryiii]

Note: you can move extras back to setup.py, then you can make them depend on either other via code, I do this for extras sometimes: https://github.com/scikit-hep/boost-histogram/blob/918caebdf922097fde92df5a5de5442d86aa04c7/setup.py#L51-L64

I often have an "all" if I do this this way.

[henryiii]

That is really weird, I don't see what would cause such a change in the styling... Wait, I wonder if it's super fences? It's now able to "nest" syntax, so... Still don't see how that would change un-fenced regular styling, like the table.

[joerick]

it might be the mkdocs update, maybe they changed the theme?

[henryiii]

Maybe it could be the newer versions? If we have customizations depending on the version of these dependencies, perhaps? Later I'll try to bisect it and see which change causes the failure.

[henryiii]

I think it was the super fences causing different HTML produced for nested constructs. No, some of the theming issues are still there. The one I was looking at (header-like thing above examples) was affected by the fences, but some of the other spacing issues are still there. Maybe things got renamed, breaking extras.css.

My real goal was to try to set up a way to add tabs (which I didn't manage yet / here, this was just some cleanup while playing with ideas). I think having tabs could really help in a few places:

• We could add action | classic | pipx setup for GitHub Actions
• We could add classic | template for Azure (with Consider including a link to Azure templates #229)
• We could make the example for setting an environment variable tabbed https://cibuildwheel.readthedocs.io/en/stable/options/#setting-options.

The tab support for mkdocs seems to be for other themes, so we'd probably have to roll our own.

[henryiii]

Should we change https://cibuildwheel.readthedocs.io/en/stable/options/#examples_4 to use https://github.com/scipy/oldest-supported-numpy ?

[YannickJadoul]

Should we change https://cibuildwheel.readthedocs.io/en/stable/options/#examples_4 to use https://github.com/scipy/oldest-supported-numpy ?

I guess so, if it's good practice, even though that would show off less the possibilities of pyproject.toml

[henryiii]

I would use:

    "numpy==1.13.3; python_version<'3.5'",
    "oldest-supported-numpy; python_version>='3.5'",

This would still show off the abilities of toml, but it would not have to be updated on every Python release, and it includes things like PyPy too!

[YannickJadoul]

That would be perfect, indeed, I'd say :-)

[henryiii]

Okay, pushed just the cleanups; the version updates can go in later, not mixed into this PR, since they are affecting the style and will need more work. Superfences too, maybe. I'd like to work on adding tabs to the above mentioned places as well eventually.

[joerick]

Just the one note on pytest dev requirement below, then I'm happy

[henryiii]

If you'd rather, I could rename all -> dev, so that requirements-dev.txt would match [dev], then the current "dev" could be "scripts" or "bin" or something like that to indicate it's the requirements for the bin directory. I think the current (in this PR) naming is more common, where you have a dev for developer requirements, a docs for building docs, and test which is just the part of dev that builds tests. Developers who want to build docs can do [dev,docs].

[henryiii]

We can tweak or iterate later, it's approved and I fixed the issue mentioned (though, technically, pytest is still there, it just is mismatched (one has a >4, one doesn't), so I plan to merge soonish. I've now started alphabetically sorting the includes, just like in requirements.txt, so that these don't get added multiple times or in different places.