Merge pull request #11666 from ethereum/robots-txt-html-extra-template-renderer

Sphinx extension for rendering `robots txt`

docs/conf.py

@@ -23,9 +23,11 @@ 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):
-    thisdir = os.path.dirname(os.path.realpath(__file__))
-    sys.path.insert(0, thisdir + '/utils')
     sphinx.add_lexer('Solidity', SolidityLexer)
     sphinx.add_lexer('Yul', YulLexer)
 
@@ -39,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,7 +161,20 @@ html_js_files = ["js/toggle.js"]
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
-html_extra_path = ["_static/css", "_static/robots.txt"]
+html_extra_path = ["_static/css"]
+
+# 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 = {
+    os.path.join(ROOT_PATH, "robots.txt.template"): {
+        'target': os.path.join(ROOT_PATH, "_static/robots.txt"),
+        'context': {'LATEST_VERSION': version},
+    }
+}
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

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,
+    }

scripts/docs.sh

@@ -27,7 +27,6 @@
 #------------------------------------------------------------------------------
 
 set -e
-scripts/update_robotstxt.sh
 cd docs
 pip3 install -r requirements.txt
 sphinx-build -nW -b html -d _build/doctrees . _build/html

scripts/update_robotstxt.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-
-#------------------------------------------------------------------------------
-# solidity is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# solidity is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with solidity.  If not, see <http://www.gnu.org/licenses/>
-#
-# (c) 2021 solidity contributors.
-#------------------------------------------------------------------------------
-
-set -eu
-
-repo_root="$(dirname "$0")/.."
-robots_template_path="${repo_root}/docs/robots.txt.template"
-robots_txt_path="${repo_root}/docs/_static/robots.txt"
-latest_version=$("${repo_root}/scripts/get_version.sh")
-
-sed -E -e "s/\{\{[[:space:]]LATEST_VERSION[[:space:]]\}\}/${latest_version}/g" "$robots_template_path" > "$robots_txt_path"