Skip to content

Commit a2919ec

Browse files
committed
Use string.Template to render indexsidebar.html
1 parent 1e856ea commit a2919ec

File tree

2 files changed

+29
-33
lines changed

2 files changed

+29
-33
lines changed

build_docs.py

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -143,16 +143,6 @@ def current_dev(self) -> Version:
143143
"""Find the current CPython version in development."""
144144
return max(self, key=Version.as_tuple)
145145

146-
def setup_indexsidebar(self, current: Version, dest_path: Path) -> None:
147-
"""Build indexsidebar.html for Sphinx."""
148-
template_path = HERE / "templates" / "indexsidebar.html"
149-
template = jinja2.Template(template_path.read_text(encoding="UTF-8"))
150-
rendered_template = template.render(
151-
current_version=current,
152-
versions=list(reversed(self)),
153-
)
154-
dest_path.write_text(rendered_template, encoding="UTF-8")
155-
156146

157147
@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
158148
class Version:
@@ -529,9 +519,9 @@ class DocBuilder:
529519
"""Builder for a CPython version and a language."""
530520

531521
version: Version
532-
versions: Versions
533522
language: Language
534523
cpython_repo: Repository
524+
indexsidebar_content: bytes
535525
switchers_content: bytes
536526
build_root: Path
537527
www_root: Path
@@ -667,10 +657,8 @@ def build(self) -> None:
667657
text = text.replace(" -A switchers=1", "")
668658
(self.checkout / "Doc" / "Makefile").write_text(text, encoding="utf-8")
669659

670-
self.versions.setup_indexsidebar(
671-
self.version,
672-
self.checkout / "Doc" / "tools" / "templates" / "indexsidebar.html",
673-
)
660+
indexsidebar_path = self.checkout / "Doc/tools/templates/indexsidebar.html"
661+
indexsidebar_path.write_bytes(self.indexsidebar_content)
674662
run_with_logging([
675663
"make",
676664
"-C",
@@ -1099,6 +1087,7 @@ def build_docs(args: argparse.Namespace) -> int:
10991087
force_build = args.force
11001088
del args.force
11011089

1090+
isb_content, eol_isb_content = render_indexsidebar(versions)
11021091
switchers_content = render_switchers(versions, languages)
11031092

11041093
build_succeeded = set()
@@ -1118,12 +1107,14 @@ def build_docs(args: argparse.Namespace) -> int:
11181107
scope = sentry_sdk.get_isolation_scope()
11191108
scope.set_tag("version", version.name)
11201109
scope.set_tag("language", language.tag)
1121-
cpython_repo.update()
1110+
cpython_repo.update()
1111+
v_isb_content = isb_content if version.status != "EOL" else eol_isb_content
11221112
builder = DocBuilder(
11231113
version,
11241114
versions,
11251115
language,
11261116
cpython_repo,
1117+
v_isb_content,
11271118
switchers_content,
11281119
**vars(args),
11291120
)
@@ -1179,6 +1170,23 @@ def parse_languages_from_config() -> Languages:
11791170
return Languages.from_json(config["defaults"], config["languages"])
11801171

11811172

1173+
def render_indexsidebar(versions: Versions) -> tuple[bytes, bytes]:
1174+
"""Pre-render indexsidebar.html for Sphinx."""
1175+
docs_by_version = f"""\
1176+
<h3>{{% trans %}}Docs by version{{% endtrans %}}</h3>
1177+
<ul>
1178+
{"\n".join([f' <li><a href="{v.url}">{v.title}</a></li>' for v in reversed(versions)])}
1179+
<li><a href="https://www.python.org/doc/versions/">{{% trans %}}All versions{{% endtrans %}}</a></li>
1180+
</ul>
1181+
"""
1182+
1183+
template_path = HERE / "templates" / "indexsidebar.html"
1184+
template = Template(template_path.read_text(encoding="UTF-8"))
1185+
rendered_template = template.substitute(DOCS_BY_VERSION=docs_by_version).encode()
1186+
eol_template = template.substitute(DOCS_BY_VERSION="").encode()
1187+
return rendered_template, eol_template
1188+
1189+
11821190
def render_switchers(versions: Versions, languages: Languages) -> bytes:
11831191
language_pairs = sorted((l.tag, l.switcher_label) for l in languages if l.in_prod) # NoQA: E741
11841192
version_pairs = [(v.name, v.picker_label) for v in reversed(versions)]

templates/indexsidebar.html

Lines changed: 5 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,18 @@
11
{#
2-
Beware, this file is rendered twice via Jinja2:
3-
- First by build_docs.py, given 'current_version' and 'versions'.
4-
- A 2nd time by Sphinx.
2+
Beware, this file is rendered twice:
3+
- First by build_docs.py using string.Template, given '$DOCS_BY_VERSION'.
4+
- Second time by Sphinx, using Jinja.
55
#}
66

7-
{% raw %}
87
<h3>{% trans %}Download{% endtrans %}</h3>
98
<p><a href="{{ pathto('download') }}">{% trans %}Download these documents{% endtrans %}</a></p>
10-
{% endraw %}
11-
{% if current_version.status != "EOL" %}
12-
{% raw %}<h3>{% trans %}Docs by version{% endtrans %}</h3>{% endraw %}
13-
<ul>
14-
{% for version in versions %}
15-
<li><a href="{{ version.url }}">{{ version.title }}</a></li>
16-
{% endfor %}
17-
{% raw %}<li><a href="https://www.python.org/doc/versions/">{% trans %}All versions{% endtrans %}</a></li>{% endraw %}
18-
</ul>
19-
{% endif %}
20-
{% raw %}
9+
$DOCS_BY_VERSION
2110
<h3>{% trans %}Other resources{% endtrans %}</h3>
2211
<ul>
2312
{# XXX: many of these should probably be merged in the main docs #}
24-
<li><a href="https://peps.python.org">{% trans %}PEP Index{% endtrans %}</a></li>
13+
<li><a href="https://peps.python.org/">{% trans %}PEP Index{% endtrans %}</a></li>
2514
<li><a href="https://wiki.python.org/moin/BeginnersGuide">{% trans %}Beginner's Guide{% endtrans %}</a></li>
2615
<li><a href="https://wiki.python.org/moin/PythonBooks">{% trans %}Book List{% endtrans %}</a></li>
2716
<li><a href="https://www.python.org/doc/av/">{% trans %}Audio/Visual Talks{% endtrans %}</a></li>
2817
<li><a href="https://devguide.python.org/">{% trans %}Python Developer’s Guide{% endtrans %}</a></li>
2918
</ul>
30-
{% endraw %}

0 commit comments

Comments
 (0)