diff --git a/docs/conf.py b/docs/conf.py index 4c7a67164..573da2465 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/ext/html_extra_template_renderer.py b/docs/ext/html_extra_template_renderer.py new file mode 100644 index 000000000..a48f20e5e --- /dev/null +++ b/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, + } diff --git a/scripts/docs.sh b/scripts/docs.sh index e2493511b..4d31277da 100755 --- a/scripts/docs.sh +++ b/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 diff --git a/scripts/update_robotstxt.sh b/scripts/update_robotstxt.sh deleted file mode 100755 index cd09c1433..000000000 --- a/scripts/update_robotstxt.sh +++ /dev/null @@ -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 -# -# (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"