Re-work Pex documentation.

[jsirois]

This change moves Pex off RTD and on to GitHub Pages. Instead of versioned docs out on RTD, only the latest docs will be available via https://docs.pex-tool.org and versioned docs will be available via GitHub Releases (for the PDF) and inside the Pex wheel and Pex PEX themselves via the new pex3 docs command that serves the appropriate docs locally, offline, with full functionality.

With this switch, docs are also now built and link-checked in CI. There should be no more RTD style misconfiguration production outages.

[jsirois]

Obviously there is alot going on here in 1 big commit. Not very reviewable! I'm going to charge forward on green CI and get out a release though to make sure all the bits work / so I can flip some DNS switches, etc. If any of you do end up providing feedback, I'll follow up.

As far as the new doc embedding goes, here is the penalty:

# Before
$ tox -epackage -- --additional-format sdist --additional-format wheel
$ du -sh dist/pex*
3.6M    dist/pex
2.8M    dist/pex-2.1.164-py2.py3-none-any.whl
4.0M    dist/pex-2.1.164.tar.gz

# After
$ tox -epackage -- --additional-format sdist --additional-format wheel --embed-docs
$ du -sh dist/pex*
4.0M    dist/pex
3.3M    dist/pex-2.1.164-py2.py3-none-any.whl
4.0M    dist/pex-2.1.164.tar.gz

So just under 500KB bigger wheel and Pex PEX.

[jsirois]

Alright, with that landed on main and my fork rebased I was able to run a test-deploy as described in the CONTRIBUTORS.md edit: https://jsirois.github.io/pex/

[jsirois]

The URIs should ~work. Still sorting through a few things on the RTD side for pex.readthedocs.io/ and pex.readthedocs.io/en/latest/ which do re-direct to the new stuff (the old explicit version links still go to RTD).

[jsirois]

Ok, the URL redirect stuff is all working now.

[jsirois]

Thanks for taking a look Huon. This looks like its all wrapped up now and working smoothly after a bit of fumbling with the RTD redirect rules.

"Cool URIs don't change"/redirects: doing large-scale website switches risks breaking old links, I imagine you may've thought of how to handle this, but I don't see it explicitly discussed?

This made me chuckle. I think you know my hard line policy on never breaking users! So no discussion needed. A discussion would have been needed for the opposite perhaps! The lack of need for notes, etc was doubly so since I did not change any site structure in the PR (there was just a single .rst -> .md for api/vars enabled by / as a test of the MyST integration, but the generated page is still api/vars.html so linking structure is unchanged). The only thing that changed from a content point of view was the new Sphinx theme (fonts / colors / positioning) and a new root URL.

[jsirois]

t looks like a fair chunk (174K) of the 500K increase might be the image assets. If one is looking for optimisations, they might be something that could be reduced?

$ wc -c assets/* | sort -n 613 assets/download.svg 884 assets/pdf.svg 946 assets/python.svg 1486 assets/github.svg 2719 assets/pex-full.svg 25312 assets/pex-icon-512x512.png 25424 assets/pex-icon-512.png 34315 assets/pex-full-dark.png 35372 assets/pex-full-light.png 47040 assets/pex.ico 174111 total

This wasn't as big a problem as it looked since only 4 of those files were linked into docs/_static, which is all that is included in the generated docs / PDF. I researched .png support for favicon though and it looks like it was supported by all major modern (last 10 years) browsers both desktop and mobile. So I just killed the .ico file and shared the 512x512 logo .png for the PDF cover page and the favicon. That could be micro-optimized further, but seemed a fine compromise that seems to work well and nets a small 20KB win in binary size for the Pex PEX and the Pex .whl.

Addressed in #2368.