Simplify generation of indexsidebar.html (#283)

Remove the double-rendering of ``indexsidebar.html``. For end-of-life
versions, change the sidebar to contain a link to the current stable
version. For non-EOL versions, overwrite the new ``_docs_by_version.html``
file with the list of links.

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
+    docs_by_version_content: bytes
     switchers_content: bytes
     build_root: Path
     www_root: Path
@@ -667,10 +657,7 @@ 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",
-            )
+            self.setup_indexsidebar()
         run_with_logging([
             "make",
             "-C",
@@ -713,6 +700,18 @@ def build_venv(self) -> None:
         run([venv_path / "bin" / "python", "-m", "pip", "freeze", "--all"])
         self.venv = venv_path
 
+    def setup_indexsidebar(self) -> None:
+        """Copy indexsidebar.html for Sphinx."""
+        tmpl_src = HERE / "templates"
+        tmpl_dst = self.checkout / "Doc" / "tools" / "templates"
+        dbv_path = tmpl_dst / "_docs_by_version.html"
+
+        shutil.copy(tmpl_src / "indexsidebar.html", tmpl_dst / "indexsidebar.html")
+        if self.version.status != "EOL":
+            dbv_path.write_bytes(self.docs_by_version_content)
+        else:
+            shutil.copy(tmpl_src / "_docs_by_version.html", dbv_path)
+
     def copy_build_to_webroot(self, http: urllib3.PoolManager) -> None:
         """Copy a given build to the appropriate webroot with appropriate rights."""
         logging.info("Publishing start.")
@@ -1099,6 +1098,7 @@ def build_docs(args: argparse.Namespace) -> int:
     force_build = args.force
     del args.force
 
+    docs_by_version_content = render_docs_by_version(versions).encode()
     switchers_content = render_switchers(versions, languages)
 
     build_succeeded = set()
@@ -1118,12 +1118,12 @@ 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()
         builder = DocBuilder(
             version,
-            versions,
             language,
             cpython_repo,
+            docs_by_version_content,
             switchers_content,
             **vars(args),
         )
@@ -1179,6 +1179,12 @@ def parse_languages_from_config() -> Languages:
     return Languages.from_json(config["defaults"], config["languages"])
 
 
+def render_docs_by_version(versions: Versions) -> str:
+    """Generate content for _docs_by_version.html."""
+    links = [f'<li><a href="{v.url}">{v.title}</a></li>' for v in reversed(versions)]
+    return "\n".join(links)
+
+
 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/_docs_by_version.html

@@ -0,0 +1,11 @@
+{#
+This file is only used in indexsidebar.html, where it is included in the docs
+by version list. For non-end-of-life branches, build_docs.py overwrites this
+list with the full list of versions.
+
+Keep the following two files synchronised:
+* cpython/Doc/tools/templates/_docs_by_version.html
+* docsbuild-scripts/templates/_docs_by_version.html
+#}
+<li><a href="https://docs.python.org/3/">{% trans %}Stable{% endtrans %}</a></li>
+<li><a href="https://docs.python.org/dev/">{% trans %}In development{% endtrans %}</a></li>

templates/indexsidebar.html

@@ -1,30 +1,17 @@
-{#
-Beware, this file is rendered twice via Jinja2:
-- First by build_docs.py, given 'current_version' and 'versions'.
-- A 2nd time by Sphinx.
-#}
-
-{% 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 %}
+<h3>{% trans %}Docs by version{% endtrans %}</h3>
 <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 %}
+  {# _docs_by_version.html is overwritten by build_docs.py for non-EOL versions #}
+  {% include "_docs_by_version.html" without context %}
+  <li><a href="https://www.python.org/doc/versions/">{% trans %}All versions{% endtrans %}</a></li>
 </ul>
-{% endif %}
-{% raw %}
 <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 %}