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:
committed by
GitHub
parent
bbdc6f5465
commit
8b0637ddcc
+8
-15
@@ -26,8 +26,8 @@ checkout_repo_msg() {
|
||||
echo "clone ${GHPAGESREPO} to ${PUBLICDIR}:"
|
||||
}
|
||||
|
||||
if ! type sphinx-versioning >/dev/null; then
|
||||
echo "install sphinx-versioning and come back"
|
||||
if ! type sphinx-multiversion >/dev/null; then
|
||||
echo "install sphinx-multiversion and come back"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
@@ -49,11 +49,11 @@ else
|
||||
read -r
|
||||
fi
|
||||
|
||||
pushd "$PUBLICDIR"
|
||||
pushd "$PUBLICDIR"
|
||||
|
||||
echo "verify we're in the GitHub pages repo..."
|
||||
git remote get-url origin | grep -E "^${GHPAGESREPO}\$"
|
||||
if [ "$?" -ne "0" ] ;then
|
||||
if [ "$?" -ne "0" ] ;then
|
||||
checkout_repo_msg
|
||||
echo "finished checkout, please run again"
|
||||
exit 1
|
||||
@@ -73,22 +73,15 @@ popd
|
||||
|
||||
echo "building site"
|
||||
|
||||
flags="$(python3 gen-sphinx-versioning-flags.py)"
|
||||
set -e
|
||||
sphinx-versioning build \
|
||||
$flags \
|
||||
docs ./public_git \
|
||||
-- -c sphinxconf # older conf.py throw errors because they used
|
||||
# version = subprocess.show_output(["git", "describe"])
|
||||
# which fails when building with sphinxcontrib-versioning
|
||||
set +e
|
||||
python3 run-sphinx-multiversion.py . ./public_git
|
||||
|
||||
|
||||
CURRENT_COMMIT=$(git rev-parse HEAD)
|
||||
git status --porcelain
|
||||
if [[ "$(git status --porcelain)" != "" ]]; then
|
||||
CURRENT_COMMIT="${CURRENT_COMMIT}(dirty)"
|
||||
CURRENT_COMMIT="${CURRENT_COMMIT}(dirty)"
|
||||
fi
|
||||
COMMIT_MSG="sphinx-versioning render from publish.sh - $(date -u) - ${CURRENT_COMMIT}"
|
||||
COMMIT_MSG="render from publish.sh - $(date -u) - ${CURRENT_COMMIT}"
|
||||
|
||||
pushd "$PUBLICDIR"
|
||||
|
||||
|
||||
Reference in New Issue
Block a user