From 6360ad789b2c3235086ec4d8e16f5bf7576cbb3b Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 23 Sep 2024 18:53:02 +0100 Subject: [PATCH 1/5] Improve type hints (use Sequence) --- build_docs.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/build_docs.py b/build_docs.py index a3971a5..961c48c 100755 --- a/build_docs.py +++ b/build_docs.py @@ -21,6 +21,7 @@ """ from argparse import ArgumentParser +from collections.abc import Sequence from contextlib import suppress, contextmanager from dataclasses import dataclass import filecmp @@ -372,7 +373,7 @@ def edit(file: Path): def setup_switchers( - versions: Iterable[Version], languages: Iterable[Language], html_root: Path + versions: Sequence[Version], languages: Sequence[Language], html_root: Path ): """Setup cross-links between CPython versions: - Cross-link various languages in a language switcher @@ -617,9 +618,9 @@ class DocBuilder: """Builder for a CPython version and a language.""" version: Version - versions: Iterable[Version] + versions: Sequence[Version] language: Language - languages: Iterable[Language] + languages: Sequence[Language] cpython_repo: Repository build_root: Path www_root: Path @@ -1127,7 +1128,7 @@ def parse_versions_from_devguide(http: urllib3.PoolManager) -> list[Version]: return versions -def parse_languages_from_config(): +def parse_languages_from_config() -> list[Language]: """Read config.toml to discover languages to build.""" config = tomlkit.parse((HERE / "config.toml").read_text(encoding="UTF-8")) languages = [] From 2828c2b2f1112b038638a73153c5cbf77a4306f6 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 23 Sep 2024 18:54:44 +0100 Subject: [PATCH 2/5] Remove needless sorts --- build_docs.py | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/build_docs.py b/build_docs.py index 961c48c..a77371b 100755 --- a/build_docs.py +++ b/build_docs.py @@ -182,9 +182,7 @@ def setup_indexsidebar(self, versions, dest_path): sidebar_file.write( sidebar_template.render( current_version=self, - versions=sorted( - versions, key=lambda v: version_to_tuple(v.name), reverse=True - ), + versions=versions[::-1], ) ) @@ -339,12 +337,7 @@ def locate_nearest_version(available_versions, target_version): '3.7' """ - available_versions_tuples = sorted( - [ - version_to_tuple(available_version) - for available_version in set(available_versions) - ] - ) + available_versions_tuples = sorted(map(version_to_tuple, set(available_versions))) target_version_tuple = version_to_tuple(target_version) try: found = available_versions_tuples[ @@ -402,11 +395,7 @@ def setup_switchers( OrderedDict( [ (version.name, version.picker_label) - for version in sorted( - versions, - key=lambda v: version_to_tuple(v.name), - reverse=True, - ) + for version in reversed(versions) ] ) ), From 988128e0d6e7f4b35ee968be1a36695f328d898f Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 23 Sep 2024 18:55:10 +0100 Subject: [PATCH 3/5] Run languages in definition order --- build_docs.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/build_docs.py b/build_docs.py index a77371b..42e5ad0 100755 --- a/build_docs.py +++ b/build_docs.py @@ -1156,10 +1156,13 @@ def build_docs(args) -> bool: http = urllib3.PoolManager() versions = parse_versions_from_devguide(http) languages = parse_languages_from_config() + # Reverse languages but not versions, because we take version-language + # pairs from the end of the list, effectively reversing it. + # This runs languages in config.toml order and versions newest first. todo = [ (version, language) for version in Version.filter(versions, args.branch) - for language in Language.filter(languages, args.languages) + for language in reversed(Language.filter(languages, args.languages)) ] del args.branch del args.languages From 4eb435ed09d5914e0f24672321f695b6c34c6fcb Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 23 Sep 2024 18:58:24 +0100 Subject: [PATCH 4/5] Remove OrderedDict --- build_docs.py | 25 +++++-------------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/build_docs.py b/build_docs.py index 42e5ad0..a62efce 100755 --- a/build_docs.py +++ b/build_docs.py @@ -37,7 +37,6 @@ import subprocess import sys from bisect import bisect_left as bisect -from collections import OrderedDict from datetime import datetime as dt, timezone from pathlib import Path from string import Template @@ -372,6 +371,9 @@ def setup_switchers( - Cross-link various languages in a language switcher - Cross-link various versions in a version switcher """ + languages_map = dict(sorted((l.tag, l.name) for l in languages if l.in_prod)) + versions_map = {v.name: v.picker_label for v in reversed(versions)} + with open( HERE / "templates" / "switchers.js", encoding="UTF-8" ) as switchers_template_file: @@ -380,25 +382,8 @@ def setup_switchers( switchers_path.write_text( template.safe_substitute( { - "LANGUAGES": json.dumps( - OrderedDict( - sorted( - [ - (language.tag, language.name) - for language in languages - if language.in_prod - ] - ) - ) - ), - "VERSIONS": json.dumps( - OrderedDict( - [ - (version.name, version.picker_label) - for version in reversed(versions) - ] - ) - ), + "LANGUAGES": json.dumps(languages_map), + "VERSIONS": json.dumps(versions_map), } ), encoding="UTF-8", From a00bf2bde0569ba9fcb9b21e612e737714f1055b Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 23 Sep 2024 19:16:00 +0100 Subject: [PATCH 5/5] Use keyword-arguments --- build_docs.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/build_docs.py b/build_docs.py index a62efce..2ebc312 100755 --- a/build_docs.py +++ b/build_docs.py @@ -381,10 +381,8 @@ def setup_switchers( switchers_path = html_root / "_static" / "switchers.js" switchers_path.write_text( template.safe_substitute( - { - "LANGUAGES": json.dumps(languages_map), - "VERSIONS": json.dumps(versions_map), - } + LANGUAGES=json.dumps(languages_map), + VERSIONS=json.dumps(versions_map), ), encoding="UTF-8", )