docs: switch to sphinx-multiversion for multi-versioned docs (#734)

The sphinxcontrib-versioning seems unmaintainted and I can't
get the fork that we used before this PR working on Python 3.10.

The situation wrt maintenance doesn't seem much better for
sphinx-multiversion, but, at least I could get it to work
with current sphinx versions.

The main problem with sphinx-multiversion is that it doesn't render
anything at `/`. I.e., `https://zrepl.github.io/configuration.html` will
be 404.
That's different from `sphinxcontrib-versioning`, and thus switching
to sphinx-multiversion would break URLs.
We host on GitHub pages and don't control the webserver,
so, we can't use webserver-level redirects to keep the URLs working.
We could create JS-level redirects, or `http-equiv`, but that's ugly as
well.
The simplest solution was to fork sphinx-multiversion and hard-code
zrepl's specific needs into that fork.
The fork is based off v0.2.4 and pinned via requirements.txt.
Here are its unique commits:
https://github.com/Holzhaus/sphinx-multiversion/compare/master...zrepl:sphinx-multiversion:zrepl

We should revisit `sphinx-polyversion` in the future once its docs
improve.
See
https://github.com/Holzhaus/sphinx-multiversion/issues/88#issuecomment-1606221194

This PR updates the various Python packages, as I couldn't get
sphinx-multiversion to work with the (very old) versions that were
pinned in `requirements.txt` prior to this PR.
This PR's `requirements.txt` is from a clean Python 3.10 venv on Ubuntu
22.10 after running

```
pip install sphinx sphinx-rtd-theme
pip install 'git+https://github.com/zrepl/sphinx-multiversion/@52c915d7ad898d9641ec48c8bbccb7d4f079db93#egg=sphinx_multiversion'
```
This commit is contained in:
Christian Schwarz
2023-09-09 12:21:25 +02:00
committed by GitHub
parent bbdc6f5465
commit 8b0637ddcc
10 changed files with 332 additions and 256 deletions
+23 -29
View File
@@ -1,30 +1,24 @@
alabaster==0.7.12
attrs==19.1.0
Babel==2.7.0
certifi==2019.6.16
chardet==3.0.4
Click==7.0
colorclass==2.2.0
docutils==0.15.2
idna==2.8
imagesize==1.1.0
Jinja2==2.10.1
MarkupSafe==1.1.1
packaging==19.1
Pygments==2.4.2
pyparsing==2.4.2
pytz==2019.2
requests==2.22.0
six==1.12.0
snowballstemmer==1.9.1
Sphinx==1.8.5
sphinx-rtd-theme==0.4.3
sphinxcontrib-applehelp==1.0.1
sphinxcontrib-devhelp==1.0.1
sphinxcontrib-htmlhelp==1.0.2
alabaster==0.7.13
Babel==2.12.1
certifi==2023.7.22
charset-normalizer==3.2.0
docutils==0.18.1
idna==3.4
imagesize==1.4.1
Jinja2==3.1.2
MarkupSafe==2.1.3
packaging==23.1
Pygments==2.16.1
requests==2.31.0
snowballstemmer==2.2.0
Sphinx==7.2.5
sphinx-multiversion @ git+https://github.com/zrepl/sphinx-multiversion/@52c915d7ad898d9641ec48c8bbccb7d4f079db93
sphinx-rtd-theme==1.3.0
sphinxcontrib-applehelp==1.0.7
sphinxcontrib-devhelp==1.0.5
sphinxcontrib-htmlhelp==2.0.4
sphinxcontrib-jquery==4.1
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.2
sphinxcontrib-serializinghtml==1.1.3
git+https://github.com/rwblair/sphinxcontrib-versioning.git@7e3885a389a809e17ea55261316b7b0e98dbf98f#egg=sphinxcontrib-versioning
sphinxcontrib-websupport==1.1.2
urllib3==1.25.3
sphinxcontrib-qthelp==1.0.6
sphinxcontrib-serializinghtml==1.1.9
urllib3==2.0.4