Docs: refactor Python code for sphinx configuration and extensions (OSGeo#3761)

mwtoews · web-flow · commit 641749e87261 · 2023-06-23T22:58:18.000+12:00
diff --git a/HOWTO-RELEASE b/HOWTO-RELEASE
@@ -242,6 +242,14 @@ of the release.*
 3.2 Documentation
 -------------------------------------------------------------------------------
 
+Edit the Sphinx configuration docs/source/conf.py with these changes:
+
+    - Set "version" to the major project version, e.g. "9.2"
+    - Set "release" to the full project version, e.g. "9.2.1"
+    - Set "data_version" to the PROJ-data version
+    - Set "today_date = date(Y, M, D)" using the release date
+    - set "github_version" to the maintenance branch label, e.g. "9.2"
+
 HTML and PDF documentation is built using ReadTheDocs, which supports multiple
 versions. Versions are based on branch labels, e.g. "9.2". To modify settings,
 registered users must first log in. To add a version, go to
@@ -250,6 +258,3 @@ next to the maintenance branch label.
 
 The latest maintenance branch should be set as the "Default version" found at
 https://readthedocs.org/dashboard/osgeo-proj/advanced/
-
-Also edit docs/source/conf.py to change the active branch for documentation
-in the `github_version` variable.
diff --git a/docs/source/_extensions/program_with_link.py b/docs/source/_extensions/program_with_link.py
@@ -1,14 +1,17 @@
 from sphinx.domains.std import StandardDomain
 
-class MyStandardDomain(StandardDomain):
 
+class MyStandardDomain(StandardDomain):
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
-        if typ == 'program':
-            typ = 'ref'
-        return StandardDomain.resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode)
+        if typ == "program":
+            typ = "ref"
+        return StandardDomain.resolve_xref(
+            self, env, fromdocname, builder, typ, target, node, contnode
+        )
+
 
 def setup(app):
     # Override the "program" role to be an alias of "ref"
     MyStandardDomain.roles["program"] = StandardDomain.roles["ref"]
     app.add_domain(MyStandardDomain, override=True)
-    return { 'parallel_read_safe': True, 'parallel_write_safe': True }
+    return {"parallel_read_safe": True, "parallel_write_safe": True}
diff --git a/docs/source/_extensions/redirects.py b/docs/source/_extensions/redirects.py
@@ -1,39 +1,32 @@
-import os
+"""Sphinx doc extension for HTML redirects.
 
-# https://tech.signavio.com/2017/managing-sphinx-redirects
+Within conf.py, add a 'redirect_files' dict with alias/target pairs.
 
+Originally from https://tech.signavio.com/2017/managing-sphinx-redirects (dead)
+"""
+from pathlib import Path
 
-template="""<html>
+template = """\
+<html>
   <head>
-    <meta http-equiv="refresh" content="1; url=%s" />
+    <meta http-equiv="refresh" content="1; url={target}" />
     <script>
-      window.location.href = "%s"
+      window.location.href = "{target}"
     </script>
   </head>
-</html>"""
+</html>
+"""
 
 
-def gather_redirects():
-    output = {}
-
-    output.update({ 'projjson.html' : 'usage/projjson.html' })
-    return output
-
-from shutil import copyfile
-# copy legacy redirects
-def copy_legacy_redirects(app, docname): # Sphinx expects two arguments
-    if app.builder.name == 'html':
-        for key in app.config.redirect_files:
-            src = key
-            tgt = app.config.redirect_files[key]
-            html = template % (tgt, tgt)
-            with open(os.path.join(app.outdir, src), 'wb') as f:
-                f.write(html.encode('utf-8'))
-                f.close()
-
+def copy_legacy_redirects(app, docname):  # Sphinx expects two arguments
+    """Copy legacy redirects."""
+    if app.builder.name == "html":
+        for alias, target in app.config.redirect_files.items():
+            pth = Path(app.outdir) / alias
+            pth.write_text(template.format(target=target))
 
 
 def setup(app):
-    app.add_config_value('redirect_files', {}, 'html')
-    app.connect('build-finished', copy_legacy_redirects)
-    return { 'parallel_read_safe': False, 'parallel_write_safe': True }
+    app.add_config_value("redirect_files", {}, "html")
+    app.connect("build-finished", copy_legacy_redirects)
+    return {"parallel_read_safe": False, "parallel_write_safe": True}
diff --git a/docs/source/_extensions/replacements.py b/docs/source/_extensions/replacements.py
@@ -0,0 +1,19 @@
+"""Sphinx doc extension for simple word replacements.
+
+Within conf.py, add a 'replacement_pairs' dict with key/replacement pairs.
+
+With inspiration from
+https://github.com/sphinx-doc/sphinx/issues/4054#issuecomment-329097229
+"""
+
+
+def replace_words(app, docname, source):
+    result = source[0]
+    for key, value in app.config.replacement_pairs.items():
+        result = result.replace(key, value)
+    source[0] = result
+
+
+def setup(app):
+    app.add_config_value("replacement_pairs", {}, True)
+    app.connect("source-read", replace_words)
diff --git a/docs/source/bibstyle.py b/docs/source/bibstyle.py
@@ -27,16 +27,17 @@
 ###############################################################################
 
 import re
+
+from pybtex.plugin import register_plugin
 from pybtex.style.formatting.unsrt import Style as UnsrtStyle
 from pybtex.style.labels.alpha import LabelStyle
-from pybtex.plugin import register_plugin
 
 
 class LinkLabelStyle(LabelStyle):
     """Citation label used in text, and before each item in the
     References section"""
 
-    re_char_nums = re.compile(r'^[\d\w]+$')
+    re_char_nums = re.compile(r"^[\d\w]+$")
 
     def format_label(self, entry):
         """Returns BibTeX key for label
@@ -47,23 +48,25 @@ def format_label(self, entry):
         label = entry.key
         if not self.re_char_nums.match(label):
             raise KeyError(
-                'BibTeX key must contain only letters and numbers '
-                '(found {0!r})'.format(label))
+                "BibTeX key must contain only letters and numbers "
+                "(found {!r})".format(label)
+            )
         return label
 
 
 class CustomStyle(UnsrtStyle):
     """Citation style in the References section"""
+
     # TODO: Make more Harvard-like, i.e. year after name(s)
 
-    default_label_style = 'linklabel'
-    default_name_style = 'lastfirst'
-    default_sorting_style = 'author_year_title'
+    default_label_style = "linklabel"
+    default_name_style = "lastfirst"
+    default_sorting_style = "author_year_title"
 
     def __init__(self, **kwargs):
-        kwargs['abbreviate_names'] = True
+        kwargs["abbreviate_names"] = True
         UnsrtStyle.__init__(self, **kwargs)
 
 
-register_plugin('pybtex.style.labels', 'linklabel', LinkLabelStyle)
-register_plugin('pybtex.style.formatting', 'customstyle', CustomStyle)
+register_plugin("pybtex.style.labels", "linklabel", LinkLabelStyle)
+register_plugin("pybtex.style.formatting", "customstyle", CustomStyle)
diff --git a/docs/source/conf.py b/docs/source/conf.py
