From 82530caa5354c93f8a4aa057d6e2cc46db9e2a34 Mon Sep 17 00:00:00 2001
From: Juergen Repp <juergen_repp@web.de>
Date: Thu, 5 Dec 2024 22:16:40 +0100
Subject: [PATCH] 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            | 23 +++++++++++++++++++++++
 sphinx/requirements.txt   | 13 +++++++++++++
 sphinx/sphinx-finished.sh | 23 +++++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100755 sphinx/sphinx-finished.sh

diff --git a/sphinx/conf.py b/sphinx/conf.py
index 9235b35dd..69843bba3 100644
--- a/sphinx/conf.py
+++ b/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)
diff --git a/sphinx/requirements.txt b/sphinx/requirements.txt
index 28c2bdaab..c8aba8c96 100644
--- a/sphinx/requirements.txt
+++ b/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
diff --git a/sphinx/sphinx-finished.sh b/sphinx/sphinx-finished.sh
new file mode 100755
index 000000000..83a670a72
--- /dev/null
+++ b/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/\&amp;\#/\&\#/g' {} \;
+touch "${SPHINX_OUTDIR}"/.nojekyll
+
+exit 0