Create a local html_extra_template_renderer Sphinx extension

docs/conf.py

@@ -23,6 +23,10 @@ from pygments_lexer_solidity import SolidityLexer, YulLexer
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
+ROOT_PATH = os.path.dirname(os.path.realpath(__file__))
+
+sys.path.insert(0, os.path.join(ROOT_PATH, 'ext'))
+
 def setup(sphinx):
     sphinx.add_lexer('Solidity', SolidityLexer)
     sphinx.add_lexer('Yul', YulLexer)
@@ -37,7 +41,10 @@ def setup(sphinx):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [ 'sphinx_a4doc' ]
+extensions = [
+    'sphinx_a4doc',
+    'html_extra_template_renderer',
+]
 
 a4_base_path = os.path.dirname(__file__) + '/grammar'
 
@@ -156,6 +163,15 @@ html_js_files = ["js/toggle.js"]
 # directly to the root of the documentation.
 html_extra_path = ["_static/css", "_static/robots.txt"]
 
+# List of templates of static files to be included in the HTML output.
+# Keys represent paths to input files and values are dicts containing:
+# - target: The path where the rendered template should be placed.
+# - context: A dictionary listing variables that can be used inside the template.
+# All paths must be absolute.
+# Rendered templates are automatically added to html_extra_path setting.
+html_extra_templates = {
+}
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'

docs/ext/html_extra_template_renderer.py

@@ -0,0 +1,45 @@
+import os.path
+
+
+def render_html_extra_templates(app):
+    if app.builder.format != 'html':
+        # Non-HTML builders do not provide .templates.render_string(). Note that a HTML
+        # builder is still used also when building some other formats like json or epub.
+        return
+
+    for input_path, template_config in app.config.html_extra_templates.items():
+        # Requiring absolute paths simplifies the implementation.
+        if not os.path.isabs(input_path):
+            raise RuntimeError(f"Template input path is not absolute: {input_path}")
+        if not os.path.isabs(template_config['target']):
+            raise RuntimeError(f"Template target path is not absolute: {template_config['target']}")
+
+        with open(input_path, 'r') as input_file:
+            # This runs Jinja2, which supports rendering {{ }} tags among other things.
+            rendered_template = app.builder.templates.render_string(
+                input_file.read(),
+                template_config['context'],
+            )
+
+        with open(template_config['target'], 'w') as target_file:
+            target_file.write(rendered_template)
+
+        app.config.html_extra_path.append(template_config['target'])
+
+
+def setup(app):
+    app.add_config_value('html_extra_templates', default={}, rebuild='', types=dict)
+
+    # Register a handler for the env-before-read-docs event. Any event that's fired before static
+    # files get copied would do.
+    app.connect(
+        'env-before-read-docs',
+        lambda app, env, docnames: render_html_extra_templates(app)
+    )
+
+    return {
+        # NOTE: Need to access _raw_config here because setup() runs before app.config is ready.
+        'version': app.config._raw_config['version'],  # pylint: disable=protected-access
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }