readthedocs: downgrade sphinx

* The embedding of README.md did not work with new sphinx versions.
* A script to fix the generated index.html is added.

Signed-off-by: Juergen Repp <juergen_repp@web.de>

sphinx/conf.py

@@ -14,6 +14,7 @@
 # serve to show the default.
 
 import subprocess
+import os
 
 # Create (unused) root file
 with open("index.rst", "w") as index_rst:
@@ -306,3 +307,25 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+# -- Extension configuration -------------------------------------------------
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+def builder_finished_handler(app, exception):
+    if exception is None:
+        os.environ["SPHINX_OUTDIR"] = str(app.outdir)
+        script = os.path.join(app.confdir, "sphinx-finished.sh")
+        subprocess.check_call(script, shell=True)
+
+
+#
+# Hook the setup of readthedocs so we can hook into events as defined in:
+# - https://www.sphinx-doc.org/en/master/extdev/appapi.html
+#
+def setup(app):
+    app.connect("build-finished", builder_finished_handler)

sphinx/requirements.txt

@@ -1,4 +1,17 @@
+setuptools_scm[toml]>=3.4.3
+cffi>=1.0.0
+pkgconfig
+cryptography>=3.0
+asn1crypto
+packaging
+pycparser
+cffi>=1.0.0
+asn1crypto
+cryptography>=3.0
+packaging
+pyyaml
 # needed for readthedocs builds:
+sphinx==6.2.1
 GitPython
 myst_parser
 sphinx_rtd_theme

sphinx/sphinx-finished.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: BSD-2
+
+#
+# This script is configured to run as part of the sphinx build
+# through API events registered in conf.py.
+# This script runs on event build-finished.
+#
+# This would be better served by handling the events
+# html-collect-page --> for add .nojekyll
+# html-page-context --> for fixing the span's done with sed.
+#
+# For the case of time, we just left this script as is and run it as a
+# post sphinx build command event :-p
+#
+
+set -eo pipefail
+
+find "${SPHINX_OUTDIR}" -name \*.html -exec \
+  sed -i 's/\&\#/\&\#/g' {} \;
+touch "${SPHINX_OUTDIR}"/.nojekyll
+
+exit 0