Skip to content

Commit 53391b4

Browse files
hugovkhugovk
committed
Merge remote-tracking branch 'upstream/main' into log-elapsed-time
2 parents 21d094e + 76c0d0a commit 53391b4

File tree

5 files changed

+122
-113
lines changed

5 files changed

+122
-113
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
/build_root/
22
/logs/
33
/www/
4+
# temporary lock file created while building the docs
5+
build_docs.lock
46

57

68
# Created by https://www.gitignore.io/api/python

‎README.md

+19-21
Original file line numberDiff line numberDiff line change
@@ -23,34 +23,32 @@ of Sphinx we're using where:
2323

2424
Sphinx configuration in various branches:
2525

26-
========= ============= ============= ================== ==================
27-
version travis azure requirements.txt conf.py
28-
========= ============= ============= ================== ==================
29-
2.7 sphinx~=2.0.1 ø ø needs_sphinx='1.2'
30-
3.5 sphinx==1.8.2 ø ø needs_sphinx='1.8'
31-
3.6 sphinx==1.8.2 sphinx==1.8.2 ø needs_sphinx='1.2'
32-
3.7 ø ø ø ø
33-
3.8 ø ø sphinx==2.4.4 needs_sphinx='1.8'
34-
3.9 ø ø sphinx==2.4.4 needs_sphinx='1.8'
35-
3.1 ø ø sphinx==3.4.3 needs_sphinx='3.2'
36-
3.11 ø ø sphinx==4.5.0 needs_sphinx='4.2'
37-
3.12 ø ø sphinx==4.5.0 needs_sphinx='4.2'
38-
3.13 ø ø sphinx==6.2.1 needs_sphinx='4.2'
39-
========= ============= ============= ================== ==================
26+
========= ============= ================== ====================
27+
version travis requirements.txt conf.py
28+
========= ============= ================== ====================
29+
2.7 sphinx~=2.0.1 ø needs_sphinx='1.2'
30+
3.5 sphinx==1.8.2 ø needs_sphinx='1.8'
31+
3.6 sphinx==1.8.2 ø needs_sphinx='1.2'
32+
3.7 sphinx==1.8.2 sphinx==2.3.1 needs_sphinx="1.6.6"
33+
3.8 ø sphinx==2.4.4 needs_sphinx='1.8'
34+
3.9 ø sphinx==2.4.4 needs_sphinx='1.8'
35+
3.10 ø sphinx==3.4.3 needs_sphinx='3.2'
36+
3.11 ø sphinx~=7.2.0 needs_sphinx='4.2'
37+
3.12 ø sphinx~=8.0.0 needs_sphinx='6.2.1'
38+
3.13 ø sphinx~=8.0.0 needs_sphinx='6.2.1'
39+
3.14 ø sphinx~=8.0.0 needs_sphinx='6.2.1'
40+
========= ============= ================== ====================
4041

4142
Sphinx build as seen on docs.python.org:
4243

4344
========= ===== ===== ===== ===== ===== ===== ===== ===== ======= ===== ===== ======= =======
4445
version en es fr id it ja ko pl pt-br tr uk zh-cn zh-tw
4546
========= ===== ===== ===== ===== ===== ===== ===== ===== ======= ===== ===== ======= =======
46-
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
47-
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
48-
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
49-
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
5047
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
5148
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
5249
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
53-
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
54-
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
55-
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
50+
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
51+
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
52+
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
53+
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
5654
========= ===== ===== ===== ===== ===== ===== ===== ===== ======= ===== ===== ======= =======

‎build_docs.py

+35-33
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,11 @@
1010
1111
-q selects "quick build", which means to build only HTML.
1212
13-
Translations are fetched from github repositories according to PEP
14-
545. `--languages` allows to select translations, like `--languages
15-
en` to just build the english documents.
13+
Translations are fetched from GitHub repositories according to PEP
14+
545. `--languages` allows selecting translations, like `--languages
15+
en` to just build the English documents.
1616
17-
This script was originally created and by Georg Brandl in March
18-
2010.
17+
This script was originally created by Georg Brandl in March 2010.
1918
Modified by Benjamin Peterson to do CDN cache invalidation.
2019
Modified by Julien Palard to build translations.
2120
@@ -69,7 +68,7 @@
6968

7069
@total_ordering
7170
class Version:
72-
"""Represents a cpython version and its documentation builds dependencies."""
71+
"""Represents a CPython version and its documentation build dependencies."""
7372

7473
STATUSES = {"EOL", "security-fixes", "stable", "pre-release", "in development"}
7574

@@ -147,7 +146,7 @@ def filter(versions, branch=None):
147146
148147
If *branch* is given, only *versions* matching *branch* are returned.
149148
150-
Else all live version are returned (this mean no EOL and no
149+
Else all live versions are returned (this means no EOL and no
151150
security-fixes branches).
152151
"""
153152
if branch:
@@ -156,12 +155,12 @@ def filter(versions, branch=None):
156155

157156
@staticmethod
158157
def current_stable(versions):
159-
"""Find the current stable cPython version."""
158+
"""Find the current stable CPython version."""
160159
return max((v for v in versions if v.status == "stable"), key=Version.as_tuple)
161160

162161
@staticmethod
163162
def current_dev(versions):
164-
"""Find the current de cPython version."""
163+
"""Find the current CPython version in development."""
165164
return max(versions, key=Version.as_tuple)
166165

167166
@property
@@ -360,7 +359,7 @@ def locate_nearest_version(available_versions, target_version):
360359
def edit(file: Path):
361360
"""Context manager to edit a file "in place", use it as:
362361
363-
with edit("/etc/hosts") as i, o:
362+
with edit("/etc/hosts") as (i, o):
364363
for line in i:
365364
o.write(line.replace("localhoat", "localhost"))
366365
"""
@@ -376,7 +375,7 @@ def edit(file: Path):
376375
def setup_switchers(
377376
versions: Iterable[Version], languages: Iterable[Language], html_root: Path
378377
):
379-
"""Setup cross-links between cpython versions:
378+
"""Setup cross-links between CPython versions:
380379
- Cross-link various languages in a language switcher
381380
- Cross-link various versions in a version switcher
382381
"""
@@ -437,7 +436,7 @@ def build_robots_txt(
437436
):
438437
"""Disallow crawl of EOL versions in robots.txt."""
439438
if not www_root.exists():
440-
logging.info("Skipping robots.txt generation (www root does not even exists).")
439+
logging.info("Skipping robots.txt generation (www root does not even exist).")
441440
return
442441
robots_file = www_root / "robots.txt"
443442
with open(HERE / "templates" / "robots.txt", encoding="UTF-8") as template_file:
@@ -457,7 +456,7 @@ def build_sitemap(
457456
):
458457
"""Build a sitemap with all live versions and translations."""
459458
if not www_root.exists():
460-
logging.info("Skipping sitemap generation (www root does not even exists).")
459+
logging.info("Skipping sitemap generation (www root does not even exist).")
461460
return
462461
with open(HERE / "templates" / "sitemap.xml", encoding="UTF-8") as template_file:
463462
template = jinja2.Template(template_file.read())
@@ -472,7 +471,7 @@ def build_sitemap(
472471
def build_404(www_root: Path, group):
473472
"""Build a nice 404 error page to display in case PDFs are not built yet."""
474473
if not www_root.exists():
475-
logging.info("Skipping 404 page generation (www root does not even exists).")
474+
logging.info("Skipping 404 page generation (www root does not even exist).")
476475
return
477476
not_found_file = www_root / "404.html"
478477
shutil.copyfile(HERE / "templates" / "404.html", not_found_file)
@@ -550,7 +549,7 @@ def parse_args():
550549
)
551550
parser.add_argument(
552551
"--skip-cache-invalidation",
553-
help="Skip fastly cache invalidation.",
552+
help="Skip Fastly cache invalidation.",
554553
action="store_true",
555554
)
556555
parser.add_argument(
@@ -580,7 +579,7 @@ def parse_args():
580579
parser.add_argument(
581580
"--theme",
582581
default="python-docs-theme",
583-
help="Python package to use for python-docs-theme: Usefull to test branches:"
582+
help="Python package to use for python-docs-theme: Useful to test branches:"
584583
" --theme git+https://github.com/obulat/python-docs-theme@master",
585584
)
586585
args = parser.parse_args()
@@ -598,7 +597,7 @@ def parse_args():
598597

599598

600599
def setup_logging(log_directory: Path):
601-
"""Setup logging to stderr if ran by a human, or to a file if ran from a cron."""
600+
"""Setup logging to stderr if run by a human, or to a file if run from a cron."""
602601
if sys.stderr.isatty():
603602
logging.basicConfig(
604603
format="%(asctime)s %(levelname)s: %(message)s", stream=sys.stderr
@@ -615,7 +614,7 @@ def setup_logging(log_directory: Path):
615614

616615
@dataclass
617616
class DocBuilder:
618-
"""Builder for a cpython version and a language."""
617+
"""Builder for a CPython version and a language."""
619618

620619
version: Version
621620
versions: Iterable[Version]
@@ -634,7 +633,7 @@ class DocBuilder:
634633
def full_build(self):
635634
"""Tell if a full build is needed.
636635
637-
A full build is slow, it builds pdf, txt, epub, texinfo, and
636+
A full build is slow; it builds pdf, txt, epub, texinfo, and
638637
archives everything.
639638
640639
A partial build only builds HTML and does not archive, it's
@@ -664,7 +663,7 @@ def run(self) -> bool:
664663

665664
@property
666665
def checkout(self) -> Path:
667-
"""Path to cpython git clone."""
666+
"""Path to CPython git clone."""
668667
return self.build_root / "cpython"
669668

670669
def clone_translation(self):
@@ -687,7 +686,7 @@ def translation_repo(self):
687686

688687
@property
689688
def translation_branch(self):
690-
"""Some cpython versions may be untranslated, being either too old or
689+
"""Some CPython versions may be untranslated, being either too old or
691690
too new.
692691
693692
This function looks for remote branches on the given repo, and
@@ -746,7 +745,7 @@ def build(self):
746745
python = self.venv / "bin" / "python"
747746
sphinxbuild = self.venv / "bin" / "sphinx-build"
748747
blurb = self.venv / "bin" / "blurb"
749-
# Disable cpython switchers, we handle them now:
748+
# Disable CPython switchers, we handle them now:
750749

751750
def is_mac():
752751
return platform.system() == 'Darwin'
@@ -791,6 +790,7 @@ def build_venv(self):
791790
run([sys.executable, "-m", "venv", venv_path])
792791
run(
793792
[venv_path / "bin" / "python", "-m", "pip", "install", "--upgrade"]
793+
+ ["--upgrade-strategy=eager"]
794794
+ [self.theme]
795795
+ self.version.requirements,
796796
cwd=self.checkout / "Doc",
@@ -959,7 +959,7 @@ def load_state(self) -> dict:
959959
return {}
960960

961961
def save_state(self, build_duration: float):
962-
"""Save current cpython sha1 and current translation sha1.
962+
"""Save current CPython sha1 and current translation sha1.
963963
964964
Using this we can deduce if a rebuild is needed or not.
965965
"""
@@ -983,7 +983,7 @@ def save_state(self, build_duration: float):
983983

984984
def symlink(www_root: Path, language: Language, directory: str, name: str, group: str, skip_cache_invalidation: bool):
985985
"""Used by major_symlinks and dev_symlink to maintain symlinks."""
986-
if language.tag == "en": # english is rooted on /, no /en/
986+
if language.tag == "en": # English is rooted on /, no /en/
987987
path = www_root
988988
else:
989989
path = www_root / language.tag
@@ -1004,7 +1004,7 @@ def symlink(www_root: Path, language: Language, directory: str, name: str, group
10041004
def major_symlinks(
10051005
www_root: Path, group, versions: Iterable[Version], languages: Iterable[Language], skip_cache_invalidation: bool
10061006
):
1007-
"""Maintains the /2/ and /3/ symlinks for each languages.
1007+
"""Maintains the /2/ and /3/ symlinks for each language.
10081008
10091009
Like:
10101010
- /3/ → /3.9/
@@ -1018,7 +1018,7 @@ def major_symlinks(
10181018

10191019

10201020
def dev_symlink(www_root: Path, group, versions, languages, skip_cache_invalidation: bool):
1021-
"""Maintains the /dev/ symlinks for each languages.
1021+
"""Maintains the /dev/ symlinks for each language.
10221022
10231023
Like:
10241024
- /dev/ → /3.11/
@@ -1033,7 +1033,7 @@ def dev_symlink(www_root: Path, group, versions, languages, skip_cache_invalidat
10331033
def purge(*paths):
10341034
"""Remove one or many paths from docs.python.org's CDN.
10351035
1036-
To be used when a file change, so the CDN fetch the new one.
1036+
To be used when a file changes, so the CDN fetches the new one.
10371037
"""
10381038
base = "https://docs.python.org/"
10391039
for path in paths:
@@ -1045,7 +1045,7 @@ def purge(*paths):
10451045
def purge_path(www_root: Path, path: Path):
10461046
"""Recursively remove a path from docs.python.org's CDN.
10471047
1048-
To be used when a directory change, so the CDN fetch the new one.
1048+
To be used when a directory changes, so the CDN fetches the new one.
10491049
"""
10501050
purge(*[file.relative_to(www_root) for file in path.glob("**/*")])
10511051
purge(path.relative_to(www_root))
@@ -1083,7 +1083,9 @@ def parse_versions_from_devguide():
10831083
"python/devguide/main/include/release-cycle.json",
10841084
timeout=30,
10851085
).json()
1086-
return [Version.from_json(name, release) for name, release in releases.items()]
1086+
versions = [Version.from_json(name, release) for name, release in releases.items()]
1087+
versions.sort(key=Version.as_tuple)
1088+
return versions
10871089

10881090

10891091
def parse_languages_from_config():
@@ -1119,7 +1121,7 @@ def format_seconds(seconds: float) -> str:
11191121

11201122

11211123
def build_docs(args) -> bool:
1122-
"""Build all docs (each languages and each versions)."""
1124+
"""Build all docs (each language and each version)."""
11231125
logging.info("Full build start.")
11241126
start_time = perf_counter()
11251127
versions = parse_versions_from_devguide()
@@ -1144,9 +1146,9 @@ def build_docs(args) -> bool:
11441146
)
11451147
)
11461148
if sentry_sdk:
1147-
with sentry_sdk.configure_scope() as scope:
1148-
scope.set_tag("version", version.name)
1149-
scope.set_tag("language", language.tag)
1149+
scope = sentry_sdk.get_isolation_scope()
1150+
scope.set_tag("version", version.name)
1151+
scope.set_tag("language", language.tag)
11501152
builder = DocBuilder(
11511153
version, versions, language, languages, cpython_repo, **vars(args)
11521154
)

0 commit comments

Comments
 (0)