sphinx: add post build script

scripts/docs.sh was running sphinx build and then a custom post-process
command. Move this post-process command into a seperate script that is
invoked through the API extensions built into sphinx. This way servers
like ReadTheDocs can get the invocation.

This approach was discussed here:
  - readthedocs/readthedocs.org#2276

Then modified for our purposes.

Signed-off-by: William Roberts <[email protected]>

Author: William Roberts

.readthedocs.yml

@@ -2,6 +2,12 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 version: 2
+
+# stable is ubuntu-18.04 image
+#   - https://hub.docker.com/r/readthedocs/build/
+build:
+  image: stable
+
 sphinx:
   builder: html
   configuration: docs/conf.py

docs/conf.py

@@ -13,6 +13,7 @@
 import os
 import sys
 import datetime
+import subprocess
 
 from setuptools_scm import get_version
 
@@ -86,3 +87,14 @@
 # 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:
+        subprocess.check_call('docs/sphinx-finished.sh', 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)

docs/sphinx-finished.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: BSD-3
+
+#
+# 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 pages/ -name \*.html -exec \
+  sed -i 's/<span class="gp">\&gt;\&gt;\&gt; <\/span>//g' {} \;
+touch pages/.nojekyll
+
+exit 0

scripts/docs.sh

@@ -1,8 +1,5 @@
 #!/usr/bin/env sh
+# SPDX-License-Identifier: BSD-3
 set -e
 
-rm -rf pages
 sphinx-build -W -b html docs pages
-find pages/ -name \*.html -exec \
-  sed -i 's/<span class="gp">\&gt;\&gt;\&gt; <\/span>//g' {} \;
-touch pages/.nojekyll