Merge remote-tracking branch 'upstream/main' into speedup-purge

Author: hugovk

.gitignore

@@ -1,6 +1,8 @@
 /build_root/
 /logs/
 /www/
+# temporary lock file created while building the docs
+build_docs.lock
 
 
 # Created by https://www.gitignore.io/api/python

README.md

@@ -23,34 +23,32 @@ of Sphinx we're using where:
 
     Sphinx configuration in various branches:
 
-    =========  =============  =============  ==================  ==================
-      version  travis         azure          requirements.txt    conf.py
-    =========  =============  =============  ==================  ==================
-         2.7   sphinx~=2.0.1  ø              ø                   needs_sphinx='1.2'
-         3.5   sphinx==1.8.2  ø              ø                   needs_sphinx='1.8'
-         3.6   sphinx==1.8.2  sphinx==1.8.2  ø                   needs_sphinx='1.2'
-         3.7   ø              ø              ø                   ø
-         3.8   ø              ø              sphinx==2.4.4       needs_sphinx='1.8'
-         3.9   ø              ø              sphinx==2.4.4       needs_sphinx='1.8'
-         3.1   ø              ø              sphinx==3.4.3       needs_sphinx='3.2'
-         3.11  ø              ø              sphinx==4.5.0       needs_sphinx='4.2'
-         3.12  ø              ø              sphinx==4.5.0       needs_sphinx='4.2'
-         3.13  ø              ø              sphinx==6.2.1       needs_sphinx='4.2'
-    =========  =============  =============  ==================  ==================
+    =========  =============  ==================  ====================
+    version    travis         requirements.txt    conf.py
+    =========  =============  ==================  ====================
+    2.7        sphinx~=2.0.1  ø                   needs_sphinx='1.2'
+    3.5        sphinx==1.8.2  ø                   needs_sphinx='1.8'
+    3.6        sphinx==1.8.2  ø                   needs_sphinx='1.2'
+    3.7        sphinx==1.8.2  sphinx==2.3.1       needs_sphinx="1.6.6"
+    3.8        ø              sphinx==2.4.4       needs_sphinx='1.8'
+    3.9        ø              sphinx==2.4.4       needs_sphinx='1.8'
+    3.10       ø              sphinx==3.4.3       needs_sphinx='3.2'
+    3.11       ø              sphinx~=7.2.0       needs_sphinx='4.2'
+    3.12       ø              sphinx~=8.0.0       needs_sphinx='6.2.1'
+    3.13       ø              sphinx~=8.0.0       needs_sphinx='6.2.1'
+    3.14       ø              sphinx~=8.0.0       needs_sphinx='6.2.1'
+    =========  =============  ==================  ====================
 
     Sphinx build as seen on docs.python.org:
 
     =========  =====  =====  =====  =====  =====  =====  =====  =====  =======  =====  =====  =======  =======
     version    en     es     fr     id     it     ja     ko     pl     pt-br    tr     uk     zh-cn    zh-tw
     =========  =====  =====  =====  =====  =====  =====  =====  =====  =======  =====  =====  =======  =======
-    2.7        ø      2.3.1  ø      2.3.1  2.3.1  ø      2.3.1  2.3.1  ø        2.3.1  2.3.1  ø        2.3.1
-    3.5        ø      1.8.4  1.8.4  1.8.4  1.8.4  ø      1.8.4  1.8.4  ø        1.8.4  1.8.4  1.8.4    1.8.4
-    3.6        ø      2.3.1  2.3.1  2.3.1  2.3.1  ø      2.3.1  2.3.1  ø        2.3.1  2.3.1  2.3.1    2.3.1
-    3.7        2.3.1  2.3.1  2.3.1  2.3.1  2.3.1  2.3.1  2.3.1  2.3.1  2.3.1    2.3.1  2.3.1  2.3.1    2.3.1
     3.8        2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4    2.4.4  2.4.4  2.4.4    2.4.4
     3.9        2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4  2.4.4    2.4.4  2.4.4  2.4.4    2.4.4
     3.10       3.4.3  3.4.3  3.4.3  3.4.3  3.4.3  3.4.3  3.4.3  3.4.3  3.4.3    3.4.3  3.4.3  3.4.3    3.4.3
-    3.11       4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0    4.5.0  4.5.0  4.5.0    4.5.0
-    3.12       4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0  4.5.0    4.5.0  4.5.0  4.5.0    4.5.0
-    3.13       6.2.1  6.2.1  6.2.1  6.2.1  6.2.1  6.2.1  6.2.1  6.2.1  6.2.1    6.2.1  6.2.1  6.2.1    6.2.1
+    3.11       7.2.6  7.2.6  7.2.6  7.2.6  7.2.6  7.2.6  7.2.6  7.2.6  7.2.6    7.2.6  7.2.6  7.2.6    7.2.6
+    3.12       8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2    8.0.2  8.0.2  8.0.2    8.0.2
+    3.13       8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2    8.0.2  8.0.2  8.0.2    8.0.2
+    3.14       8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2  8.0.2    8.0.2  8.0.2  8.0.2    8.0.2
     =========  =====  =====  =====  =====  =====  =====  =====  =====  =======  =====  =====  =======  =======

build_docs.py

@@ -10,12 +10,11 @@
 
 -q selects "quick build", which means to build only HTML.
 
-Translations are fetched from github repositories according to PEP
-545. `--languages` allows to select translations, like `--languages
-en` to just build the english documents.
+Translations are fetched from GitHub repositories according to PEP
+545. `--languages` allows selecting translations, like `--languages
+en` to just build the English documents.
 
-This script was originally created and by Georg Brandl in March
-2010.
+This script was originally created by Georg Brandl in March 2010.
 Modified by Benjamin Peterson to do CDN cache invalidation.
 Modified by Julien Palard to build translations.
 
@@ -68,7 +67,7 @@
 
 @total_ordering
 class Version:
-    """Represents a cpython version and its documentation builds dependencies."""
+    """Represents a CPython version and its documentation build dependencies."""
 
     STATUSES = {"EOL", "security-fixes", "stable", "pre-release", "in development"}
 
@@ -146,7 +145,7 @@ def filter(versions, branch=None):
 
         If *branch* is given, only *versions* matching *branch* are returned.
 
-        Else all live version are returned (this mean no EOL and no
+        Else all live versions are returned (this means no EOL and no
         security-fixes branches).
         """
         if branch:
@@ -155,12 +154,12 @@ def filter(versions, branch=None):
 
     @staticmethod
     def current_stable(versions):
-        """Find the current stable cPython version."""
+        """Find the current stable CPython version."""
         return max((v for v in versions if v.status == "stable"), key=Version.as_tuple)
 
     @staticmethod
     def current_dev(versions):
-        """Find the current de cPython version."""
+        """Find the current CPython version in development."""
         return max(versions, key=Version.as_tuple)
 
     @property
@@ -359,7 +358,7 @@ def locate_nearest_version(available_versions, target_version):
 def edit(file: Path):
     """Context manager to edit a file "in place", use it as:
 
-    with edit("/etc/hosts") as i, o:
+    with edit("/etc/hosts") as (i, o):
         for line in i:
             o.write(line.replace("localhoat", "localhost"))
     """
@@ -375,7 +374,7 @@ def edit(file: Path):
 def setup_switchers(
     versions: Iterable[Version], languages: Iterable[Language], html_root: Path
 ):
-    """Setup cross-links between cpython versions:
+    """Setup cross-links between CPython versions:
     - Cross-link various languages in a language switcher
     - Cross-link various versions in a version switcher
     """
@@ -437,7 +436,7 @@ def build_robots_txt(
 ) -> None:
     """Disallow crawl of EOL versions in robots.txt."""
     if not www_root.exists():
-        logging.info("Skipping robots.txt generation (www root does not even exists).")
+        logging.info("Skipping robots.txt generation (www root does not even exist).")
         return
     robots_file = www_root / "robots.txt"
     with open(HERE / "templates" / "robots.txt", encoding="UTF-8") as template_file:
@@ -457,7 +456,7 @@ def build_sitemap(
 ):
     """Build a sitemap with all live versions and translations."""
     if not www_root.exists():
-        logging.info("Skipping sitemap generation (www root does not even exists).")
+        logging.info("Skipping sitemap generation (www root does not even exist).")
         return
     with open(HERE / "templates" / "sitemap.xml", encoding="UTF-8") as template_file:
         template = jinja2.Template(template_file.read())
@@ -472,7 +471,7 @@ def build_sitemap(
 def build_404(www_root: Path, group):
     """Build a nice 404 error page to display in case PDFs are not built yet."""
     if not www_root.exists():
-        logging.info("Skipping 404 page generation (www root does not even exists).")
+        logging.info("Skipping 404 page generation (www root does not even exist).")
         return
     not_found_file = www_root / "404.html"
     shutil.copyfile(HERE / "templates" / "404.html", not_found_file)
@@ -550,7 +549,7 @@ def parse_args():
     )
     parser.add_argument(
         "--skip-cache-invalidation",
-        help="Skip fastly cache invalidation.",
+        help="Skip Fastly cache invalidation.",
         action="store_true",
     )
     parser.add_argument(
@@ -580,7 +579,7 @@ def parse_args():
     parser.add_argument(
         "--theme",
         default="python-docs-theme",
-        help="Python package to use for python-docs-theme: Usefull to test branches:"
+        help="Python package to use for python-docs-theme: Useful to test branches:"
         " --theme git+https://github.com/obulat/python-docs-theme@master",
     )
     args = parser.parse_args()
@@ -598,7 +597,7 @@ def parse_args():
 
 
 def setup_logging(log_directory: Path):
-    """Setup logging to stderr if ran by a human, or to a file if ran from a cron."""
+    """Setup logging to stderr if run by a human, or to a file if run from a cron."""
     if sys.stderr.isatty():
         logging.basicConfig(
             format="%(asctime)s %(levelname)s: %(message)s", stream=sys.stderr
@@ -615,7 +614,7 @@ def setup_logging(log_directory: Path):
 
 @dataclass
 class DocBuilder:
-    """Builder for a cpython version and a language."""
+    """Builder for a CPython version and a language."""
 
     version: Version
     versions: Iterable[Version]
@@ -634,7 +633,7 @@ class DocBuilder:
     def full_build(self):
         """Tell if a full build is needed.
 
-        A full build is slow, it builds pdf, txt, epub, texinfo, and
+        A full build is slow; it builds pdf, txt, epub, texinfo, and
         archives everything.
 
         A partial build only builds HTML and does not archive, it's
@@ -664,7 +663,7 @@ def run(self, http: urllib3.PoolManager) -> bool:
 
     @property
     def checkout(self) -> Path:
-        """Path to cpython git clone."""
+        """Path to CPython git clone."""
         return self.build_root / "cpython"
 
     def clone_translation(self):
@@ -687,7 +686,7 @@ def translation_repo(self):
 
     @property
     def translation_branch(self):
-        """Some cpython versions may be untranslated, being either too old or
+        """Some CPython versions may be untranslated, being either too old or
         too new.
 
         This function looks for remote branches on the given repo, and
@@ -745,7 +744,7 @@ def build(self):
         python = self.venv / "bin" / "python"
         sphinxbuild = self.venv / "bin" / "sphinx-build"
         blurb = self.venv / "bin" / "blurb"
-        # Disable cpython switchers, we handle them now:
+        # Disable CPython switchers, we handle them now:
 
         def is_mac():
             return platform.system() == 'Darwin'
@@ -790,6 +789,7 @@ def build_venv(self):
         run([sys.executable, "-m", "venv", venv_path])
         run(
             [venv_path / "bin" / "python", "-m", "pip", "install", "--upgrade"]
+            + ["--upgrade-strategy=eager"]
             + [self.theme]
             + self.version.requirements,
             cwd=self.checkout / "Doc",
@@ -955,7 +955,7 @@ def load_state(self) -> dict:
             return {}
 
     def save_state(self, build_duration: float):
-        """Save current cpython sha1 and current translation sha1.
+        """Save current CPython sha1 and current translation sha1.
 
         Using this we can deduce if a rebuild is needed or not.
         """
@@ -987,7 +987,7 @@ def symlink(
     http: urllib3.PoolManager,
 ) -> None:
     """Used by major_symlinks and dev_symlink to maintain symlinks."""
-    if language.tag == "en":  # english is rooted on /, no /en/
+    if language.tag == "en":  # English is rooted on /, no /en/
         path = www_root
     else:
         path = www_root / language.tag
@@ -1013,7 +1013,7 @@ def major_symlinks(
     skip_cache_invalidation: bool,
     http: urllib3.PoolManager,
 ) -> None:
-    """Maintains the /2/ and /3/ symlinks for each languages.
+    """Maintains the /2/ and /3/ symlinks for each language.
 
     Like:
     - /3/ → /3.9/
@@ -1042,7 +1042,7 @@ def dev_symlink(
     skip_cache_invalidation: bool,
     http: urllib3.PoolManager,
 ) -> None:
-    """Maintains the /dev/ symlinks for each languages.
+    """Maintains the /dev/ symlinks for each language.
 
     Like:
     - /dev/ → /3.11/
@@ -1065,7 +1065,7 @@ def dev_symlink(
 def purge(http: urllib3.PoolManager, *paths: Path | str) -> None:
     """Remove one or many paths from docs.python.org's CDN.
 
-    To be used when a file change, so the CDN fetch the new one.
+    To be used when a file changes, so the CDN fetches the new one.
     """
     base = "https://docs.python.org/"
     for path in paths:
@@ -1077,7 +1077,7 @@ def purge(http: urllib3.PoolManager, *paths: Path | str) -> None:
 def purge_path(http: urllib3.PoolManager, www_root: Path, path: Path) -> None:
     """Recursively remove a path from docs.python.org's CDN.
 
-    To be used when a directory change, so the CDN fetch the new one.
+    To be used when a directory changes, so the CDN fetches the new one.
     """
     purge(http, *[file.relative_to(www_root) for file in path.glob("**/*")])
     purge(http, path.relative_to(www_root))
@@ -1118,7 +1118,9 @@ def parse_versions_from_devguide(http: urllib3.PoolManager) -> list[Version]:
         "python/devguide/main/include/release-cycle.json",
         timeout=30,
     ).json()
-    return [Version.from_json(name, release) for name, release in releases.items()]
+    versions = [Version.from_json(name, release) for name, release in releases.items()]
+    versions.sort(key=Version.as_tuple)
+    return versions
 
 
 def parse_languages_from_config():
@@ -1164,9 +1166,9 @@ def build_docs(args) -> bool:
             )
         )
         if sentry_sdk:
-            with sentry_sdk.configure_scope() as scope:
-                scope.set_tag("version", version.name)
-                scope.set_tag("language", language.tag)
+            scope = sentry_sdk.get_isolation_scope()
+            scope.set_tag("version", version.name)
+            scope.set_tag("language", language.tag)
         builder = DocBuilder(
             version, versions, language, languages, cpython_repo, **vars(args)
         )