Monkeypatch docutils to fix bibliography output

This applies the patch discussed in gh-455 dynamically on import of
`docutils`, in order to fix the broken HTML output from the
`..  bibliography` directive. We constrain `docutils` during our build
process to fix it to a version that is known-good with this change
applied.  The constraint may be dropped when docutils updates, as the
relevant patch is merged to trunk.

.github/workflows/build-live-version.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -c constraints.txt -r requirements.txt
 
       - name: Generate HTML
         run: make html

.github/workflows/publish-live-version.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -c constraints.txt -r requirements.txt
 
       - name: Generate HTML
         run: make html

Makefile

@@ -23,7 +23,7 @@ BUILDDIR      = build
 .PHONY: help Makefile install lint test
 
 install:
-	pip install -r requirements.txt
+	pip install -c constraints.txt -r requirements.txt
 
 # Put it first so that "make" without argument is like "make help".
 help:

constraints.txt

@@ -0,0 +1,4 @@
+# Pin docutils to a known-good version with the `Node.previous_sibling`
+# monkey-patching as applied in `source/conf.py`.  Can be relaxed once docutils
+# releases a new version with the reference patch applied.
+docutils==0.19.0

source/conf.py

@@ -76,3 +76,19 @@ html_css_files = ['colors.css']
 numfig = True
 # Necessary setting for sphinxcontrib-bibtex >= 2.0.0
 bibtex_bibfiles = ['bibliography.bib']
+
+# Monkey-patch docutils 0.19.0 with a fix to `Node.previous_sibling` that is the
+# root cause of incorrect HTML output for bibliograhy files (see gh-455).
+# docutils is pinned in `constraints.txt` to a version that is known to work
+# with this patch.  If docutils releases a new version, this monkeypatching and
+# the constraint may be able to be dropped.
+import docutils.nodes
+
+# This method is taken from docutils revision r9126, which is to a file
+# explicitly placed in the public domain; there is no licence clause.
+def previous_sibling(self):
+    if not self.parent:
+        return None
+    index = self.parent.index(self)
+    return self.parent[index - 1] if index > 0 else None
+docutils.nodes.Node.previous_sibling = previous_sibling