Use string.Template to render indexsidebar.html

Author: AA-Turner

build_docs.py

@@ -143,16 +143,6 @@ def current_dev(self) -> Version:
         """Find the current CPython version in development."""
         return max(self, key=Version.as_tuple)
 
-    def setup_indexsidebar(self, current: Version, dest_path: Path) -> None:
-        """Build indexsidebar.html for Sphinx."""
-        template_path = HERE / "templates" / "indexsidebar.html"
-        template = jinja2.Template(template_path.read_text(encoding="UTF-8"))
-        rendered_template = template.render(
-            current_version=current,
-            versions=list(reversed(self)),
-        )
-        dest_path.write_text(rendered_template, encoding="UTF-8")
-
 
 @dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
 class Version:
@@ -529,9 +519,9 @@ class DocBuilder:
     """Builder for a CPython version and a language."""
 
     version: Version
-    versions: Versions
     language: Language
     cpython_repo: Repository
+    indexsidebar_content: bytes
     switchers_content: bytes
     build_root: Path
     www_root: Path
@@ -667,10 +657,8 @@ def build(self) -> None:
                 text = text.replace(" -A switchers=1", "")
                 (self.checkout / "Doc" / "Makefile").write_text(text, encoding="utf-8")
 
-            self.versions.setup_indexsidebar(
-                self.version,
-                self.checkout / "Doc" / "tools" / "templates" / "indexsidebar.html",
-            )
+            indexsidebar_path = self.checkout / "Doc/tools/templates/indexsidebar.html"
+            indexsidebar_path.write_bytes(self.indexsidebar_content)
         run_with_logging([
             "make",
             "-C",
@@ -1099,6 +1087,7 @@ def build_docs(args: argparse.Namespace) -> int:
     force_build = args.force
     del args.force
 
+    isb_content, eol_isb_content = render_indexsidebar(versions)
     switchers_content = render_switchers(versions, languages)
 
     build_succeeded = set()
@@ -1118,12 +1107,14 @@ def build_docs(args: argparse.Namespace) -> int:
             scope = sentry_sdk.get_isolation_scope()
             scope.set_tag("version", version.name)
             scope.set_tag("language", language.tag)
-            cpython_repo.update()
+        cpython_repo.update()
+        v_isb_content = isb_content if version.status != "EOL" else eol_isb_content
         builder = DocBuilder(
             version,
             versions,
             language,
             cpython_repo,
+            v_isb_content,
             switchers_content,
             **vars(args),
         )
@@ -1179,6 +1170,23 @@ def parse_languages_from_config() -> Languages:
     return Languages.from_json(config["defaults"], config["languages"])
 
 
+def render_indexsidebar(versions: Versions) -> tuple[bytes, bytes]:
+    """Pre-render indexsidebar.html for Sphinx."""
+    docs_by_version = f"""\
+<h3>{{% trans %}}Docs by version{{% endtrans %}}</h3>
+<ul>
+{"\n".join([f'  <li><a href="{v.url}">{v.title}</a></li>' for v in reversed(versions)])}
+  <li><a href="https://www.python.org/doc/versions/">{{% trans %}}All versions{{% endtrans %}}</a></li>
+</ul>
+"""
+
+    template_path = HERE / "templates" / "indexsidebar.html"
+    template = Template(template_path.read_text(encoding="UTF-8"))
+    rendered_template = template.substitute(DOCS_BY_VERSION=docs_by_version).encode()
+    eol_template = template.substitute(DOCS_BY_VERSION="").encode()
+    return rendered_template, eol_template
+
+
 def render_switchers(versions: Versions, languages: Languages) -> bytes:
     language_pairs = sorted((l.tag, l.switcher_label) for l in languages if l.in_prod)  # NoQA: E741
     version_pairs = [(v.name, v.picker_label) for v in reversed(versions)]

templates/indexsidebar.html

@@ -1,30 +1,18 @@
 {#
-Beware, this file is rendered twice via Jinja2:
-- First by build_docs.py, given 'current_version' and 'versions'.
-- A 2nd time by Sphinx.
+Beware, this file is rendered twice:
+- First by build_docs.py using string.Template, given '$DOCS_BY_VERSION'.
+- Second time by Sphinx, using Jinja.
 #}
 
-{% raw %}
 <h3>{% trans %}Download{% endtrans %}</h3>
 <p><a href="{{ pathto('download') }}">{% trans %}Download these documents{% endtrans %}</a></p>
-{% endraw %}
-{% if current_version.status != "EOL" %}
-{% raw %}<h3>{% trans %}Docs by version{% endtrans %}</h3>{% endraw %}
-<ul>
-  {% for version in versions %}
-  <li><a href="{{ version.url }}">{{ version.title }}</a></li>
-  {% endfor %}
-  {% raw %}<li><a href="https://www.python.org/doc/versions/">{% trans %}All versions{% endtrans %}</a></li>{% endraw %}
-</ul>
-{% endif %}
-{% raw %}
+$DOCS_BY_VERSION
 <h3>{% trans %}Other resources{% endtrans %}</h3>
 <ul>
   {# XXX: many of these should probably be merged in the main docs #}
-  <li><a href="https://peps.python.org">{% trans %}PEP Index{% endtrans %}</a></li>
+  <li><a href="https://peps.python.org/">{% trans %}PEP Index{% endtrans %}</a></li>
   <li><a href="https://wiki.python.org/moin/BeginnersGuide">{% trans %}Beginner's Guide{% endtrans %}</a></li>
   <li><a href="https://wiki.python.org/moin/PythonBooks">{% trans %}Book List{% endtrans %}</a></li>
   <li><a href="https://www.python.org/doc/av/">{% trans %}Audio/Visual Talks{% endtrans %}</a></li>
   <li><a href="https://devguide.python.org/">{% trans %}Python Developer’s Guide{% endtrans %}</a></li>
 </ul>
-{% endraw %}