Centralize info for API documentation

[HalfWhitt]

This is an attempt to consolidate some of the info for the API component documentation, so that there's less repetition, and thus less possibility of drift. It also fixes #3818 (changing all the title/links in the "APIs by platform" page to normal text and page links instead of code cross references) and makes a bit of progress toward #3819 by fixing some title case in the touched files.

As of beeware/beeware-docs-tools#69, the BeeWare docs tools support the creation of custom macros in Python code. I've added a macros module, and defined macros in it for generating:

• The tables on the two API component reference pages (both the "main" one with descriptions, and the one with platform support)
• The repeated content at the top of each component's page:
  • Title
  • Description
  • Platform support (tabbed view for visual widgets, table for non-visual, and entirely blank for platform-agnostic things like sources)

There was already some drift between the descriptions on the index page, the individual pages, and the CSV; I mostly went with what was on the index, except for a few which were more fleshed out on the individual page. I've also put a period at the end of each, since this was inconsistent (and some do contain full sentences).

As John pointed out, there was some drift in the supported platforms in the tabbed screenshot views too; now they pull directly from the CSV. They also all include automatically generated alt text, e.g. "MainWindow on macOS". ImageView was the sole component that used the same image file for multiple platforms; rather than make an exception in the code, I copied and renamed the file. I imagine we can live with an extra 30 KB... but let me know if you'd prefer the opposite approach.

I also fixed a broken link that was pointing to tutorial/tutorial-1.html. (Edit: not only did I accidentally not commit that, I'd missed a newer change to the same link and had to rebase to pull it in.) Speaking of which, all the ".html" URLs from the old docs are broken with this overhaul. Perhaps mkdocs-redirects would be worth looking into... but this PR is already pretty big. [Edit: handled in RTD settings]

Speaking of things that might still be good to do:

• I still think it would be good to combine the two API reference indices if possible — possibly with tabs, if feasible.
• I was able to simplify the gnarly CSS selectors for table styling a little bit by replacing the header's IDs with a class. It would be really nice, of course, to simply apply a class directly to the tables. Even though the list-attrs plugin doesn't support this, it looks like something workable might be possible using either this pymdownx.blocks.html approach or maybe even this fork of attr-list (or applying its changes to the more current code).
• I renamed widgets_by_platform.csv to apis_by_platform.csv, since it's not just widgets (and to match the pages' actual title). I didn't change the markdown file's name though, or any others, to make them more consistent or in line with their titles. That can be a separate thing to (potentially) do, and appropriately redirect.

PR Checklist:

• All new features have been tested
• All new features have been documented
• I have read the CONTRIBUTING.md file
• I will abide by the code of conduct

[HalfWhitt]

Note: if you're building this locally, make sure to pass -r to tox to rebuild the environment. The dependencies list hasn't changed, but it needs the updated version of BeeWare Docs Tools.

[kattni]

This looks great! As RTD was being unusually slow, I pulled the PR down to build, and go through every updated page to verify how it's rendering. I found a couple of issues, noted below. The one that might toss a wrench into things is the need for the Toga APIs By Platform Component list to be primarily formatted as inline code. Otherwise, this is an excellent update. Cheers!

[kattni]

Speaking of which, all the ".html" URLs from the old docs are broken with this overhaul. Perhaps mkdocs-redirects would be worth looking into... but this PR is already pretty big.

I'm not sure this is necessary. That said, I know Russ has thing about broken links, so I'll let him speak to this.

This PR isn't so big that I wouldn't recommend adding this if desired. A lot of this content is repeated, so the review process is pretty smooth, which is the concern.

[freakboy3742]

Speaking of which, all the ".html" URLs from the old docs are broken with this overhaul. Perhaps mkdocs-redirects would be worth looking into... but this PR is already pretty big.

I'm not sure this is necessary. That said, I know Russ has thing about broken links, so I'll let him speak to this.

I do indeed have a thing about broken links. If there's a relatively simple workaround that will turn all .html references into "bare" redirects on the same page, I think that would be worth adding - all the published docs references out there have .html suffixes, and they're all going to break when the current main becomes stable.

However, I agree it that be a separate PR.

[HalfWhitt]

@johnzhou721 Heads up / reminder on incoming merge conflicts for #3769 — sorry!

[johnzhou721]

@HalfWhitt No, not your fault. I should've caught this issue and shaved this yak sooner when I thought about updating the Qt documentation.

[freakboy3742]

An awesome cleanup - thanks!

[kattni]

Looks good! Thanks for the update! I really like the YAML setup.