Skip to content

Commit f6d1625

Browse files
lwasserlwasser
committed
Fix: rebase main
1 parent 65bdd1b commit f6d1625

File tree

1 file changed

+219
-42
lines changed

1 file changed

+219
-42
lines changed

‎noxfile.py

Lines changed: 219 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -5,79 +5,256 @@
55

66
nox.options.reuse_existing_virtualenvs = True
77

8-
OUTPUT_DIR = "_build"
9-
docs_dir = os.path.join("_build", "html")
10-
build_command = ["-b", "html", ".", docs_dir]
8+
## Sphinx related options
9+
10+
# Sphinx output and source directories
11+
BUILD_DIR = "_build"
12+
OUTPUT_DIR = pathlib.Path(BUILD_DIR, "html")
13+
SOURCE_DIR = pathlib.Path(".")
14+
15+
# Location of the translation templates
16+
TRANSLATION_TEMPLATE_DIR = pathlib.Path(BUILD_DIR, "gettext")
17+
TRANSLATION_LOCALES_DIR = pathlib.Path("locales")
18+
19+
# Sphinx build commands
20+
SPHINX_BUILD = "sphinx-build"
21+
SPHINX_AUTO_BUILD = "sphinx-autobuild"
22+
23+
# Sphinx parameters used to build the guide
24+
BUILD_PARAMETERS = ["-b", "html"]
25+
26+
# Sphinx parameters used to test the build of the guide
27+
TEST_PARAMETERS = ["-W", "--keep-going", "-E", "-a"]
28+
29+
# Sphinx parameters to generate translation templates
30+
TRANSLATION_TEMPLATE_PARAMETERS = ["-b", "gettext"]
31+
32+
# Sphinx-autobuild ignore and include parameters
33+
AUTOBUILD_IGNORE = [
34+
"_build",
35+
".nox",
36+
"build_assets",
37+
"tmp",
38+
]
39+
AUTOBUILD_INCLUDE = [pathlib.Path("_static", "pyos.css")]
40+
41+
## Localization options (translations)
42+
43+
# List of languages for which locales will be generated in (/locales/<lang>)
44+
LANGUAGES = ["es"]
45+
46+
# List of languages that should be built when releasing the guide (docs or docs-test sessions)
47+
RELEASE_LANGUAGES = []
1148

1249

1350
@nox.session
1451
def docs(session):
52+
"""Build the packaging guide."""
1553
session.install("-e", ".")
16-
cmd = ["sphinx-build"]
17-
cmd.extend(build_command + session.posargs)
18-
session.run(*cmd)
54+
session.run(
55+
SPHINX_BUILD,
56+
*BUILD_PARAMETERS,
57+
SOURCE_DIR,
58+
OUTPUT_DIR,
59+
*session.posargs,
60+
)
61+
# When building the guide, also build the translations in RELEASE_LANGUAGES
62+
session.notify("build-translations", ["release-build"])
1963

2064

2165
@nox.session(name="docs-test")
2266
def docs_test(session):
2367
"""
24-
Same as `docs`, but rebuild everything and fail on warnings for testing
68+
Build the packaging guide with more restricted parameters.
69+
70+
Note: this is the session used in CI/CD to release the guide.
2571
"""
2672
session.install("-e", ".")
27-
cmd = ["sphinx-build"]
28-
cmd.extend(["-W", "--keep-going", "-E", "-a"])
29-
cmd.extend(build_command + session.posargs)
30-
session.run(*cmd)
73+
session.run(
74+
SPHINX_BUILD,
75+
*BUILD_PARAMETERS,
76+
*TEST_PARAMETERS,
77+
SOURCE_DIR,
78+
OUTPUT_DIR,
79+
*session.posargs,
80+
)
81+
# When building the guide with additional parameters, also build the translations in RELEASE_LANGUAGES
82+
# with those same parameters.
83+
session.notify("build-translations", ["release-build", *TEST_PARAMETERS])
3184

3285

3386
@nox.session(name="docs-live")
3487
def docs_live(session):
35-
session.install("-e", ".")
88+
"""
89+
Build and launch a local copy of the guide.
3690
37-
AUTOBUILD_IGNORE = [
38-
"_build",
39-
"build_assets",
40-
"tmp",
41-
]
91+
This session will use sphinx-autobuild to build the guide and launch a local server so you can
92+
browse it locally. It will automatically rebuild the guide when changes are detected in the source.
4293
43-
# Explicitly include custom CSS in each build since
44-
# sphinx doesn't think _static files should change since,
45-
# well, they're static.
46-
# Include these as the final `filenames` argument
94+
It can be used with the language parameter to build a specific translation, for example:
4795
48-
AUTOBUILD_INCLUDE = [os.path.join("_static", "pyos.css")]
96+
nox -s docs-live -- -D language=es
4997
50-
# ----------------
51-
# Assemble command
52-
cmd = ["sphinx-autobuild"]
98+
Note: The docs-live-lang session below is provided as a convenience session for beginner contributors
99+
so they don't need to remember the specific sphinx-build parameters to build a different language.
100+
"""
101+
session.install("-e", ".")
102+
cmd = [
103+
SPHINX_AUTO_BUILD,
104+
*BUILD_PARAMETERS,
105+
SOURCE_DIR,
106+
OUTPUT_DIR,
107+
*session.posargs,
108+
]
53109
for folder in AUTOBUILD_IGNORE:
54110
cmd.extend(["--ignore", f"*/{folder}/*"])
111+
# This part was commented in the previous version of the nox file, keeping the same here
112+
# for folder in AUTOBUILD_INCLUDE:
113+
# cmd.extend(["--watch", folder])
114+
session.run(*cmd)
55115

56-
# cmd.extend(build_command)
57-
cmd.extend(build_command + session.posargs)
58116

59-
# Use positional arguments if we have them
60-
# if len(session.posargs) > 0:
61-
# cmd.extend(session.posargs)
62-
# # Otherwise use default output and include directory
63-
# else:
64-
# cmd.extend(AUTOBUILD_INCLUDE)
117+
@nox.session(name="docs-live-lang")
118+
def docs_live_lang(session):
119+
"""
120+
A convenience session for beginner contributors to use the docs-live session with
121+
a specific language.
65122
66-
session.run(*cmd)
123+
It expects the language code to be passed as the first positional argument, so it needs
124+
to be called with from the command line with the following syntax:
67125
126+
nox -s docs-live-lang -- LANG
68127
69-
@nox.session(name="docs-clean")
70-
def clean_dir(dir_path=docs_dir):
71-
"""
72-
Clean out the docs directory used in the
73-
live build.
128+
where LANG is one of the available languages defined in LANGUAGES.
129+
For example, for Spanish: nox -s docs-live-lang -- es
74130
"""
75-
dir_path = pathlib.Path(dir_path)
76-
dir_contents = dir_path.glob("*")
131+
if not session.posargs:
132+
session.error(
133+
"Please provide a language using:\n\n "
134+
"nox -s docs-live-lang -- LANG\n\n "
135+
f" where LANG is one of: {LANGUAGES}"
136+
)
137+
lang = session.posargs[0]
138+
if lang in LANGUAGES:
139+
session.posargs.pop(0)
140+
session.notify(
141+
"docs-live", ("-D", f"language={lang}", *session.posargs)
142+
)
143+
else:
144+
session.error(
145+
f"[{lang}] locale is not available. Try using:\n\n "
146+
"nox -s docs-live-lang -- LANG\n\n "
147+
f"where LANG is one of: {LANGUAGES}"
148+
)
149+
77150

151+
@nox.session(name="docs-clean")
152+
def clean_dir(session):
153+
"""Clean out the docs directory used in the live build."""
154+
session.warn(f"Cleaning out {OUTPUT_DIR}")
155+
dir_contents = OUTPUT_DIR.glob("*")
78156
for content in dir_contents:
79-
print(content)
157+
session.log(f"removing {content}")
80158
if content.is_dir():
81159
shutil.rmtree(content)
82160
else:
83161
os.remove(content)
162+
163+
164+
@nox.session(name="update-translations")
165+
def update_translations(session):
166+
"""
167+
Update the translation files (./locales/*/.po) for all languages translations.
168+
169+
Note: this step is important because it makes sure that the translation files are
170+
up to date with the latest changes in the guide.
171+
"""
172+
session.install("-e", ".")
173+
session.install("sphinx-intl")
174+
session.log("Updating templates (.pot)")
175+
session.run(
176+
SPHINX_BUILD,
177+
*TRANSLATION_TEMPLATE_PARAMETERS,
178+
SOURCE_DIR,
179+
TRANSLATION_TEMPLATE_DIR,
180+
*session.posargs,
181+
)
182+
for lang in LANGUAGES:
183+
session.log(f"Updating .po files for [{lang}] translation")
184+
session.run(
185+
"sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang
186+
)
187+
188+
189+
@nox.session(name="build-languages")
190+
def build_languages(session):
191+
"""
192+
Build the translations of the guide for the specified language.
193+
194+
Note: This sessions expects a list of languages to build in the first position of the session arguments.
195+
It does not need to be called directly, it is started by build_translations session.
196+
"""
197+
if not session.posargs:
198+
session.error(
199+
"Please provide the list of languages to build the translation for"
200+
)
201+
languages_to_build = session.posargs.pop(0)
202+
203+
session.install("-e", ".")
204+
for lang in languages_to_build:
205+
if lang not in LANGUAGES:
206+
session.warn(f"Language [{lang}] is not available for translation")
207+
continue
208+
session.log(f"Building [{lang}] guide")
209+
session.run(
210+
SPHINX_BUILD,
211+
*BUILD_PARAMETERS,
212+
"-D",
213+
f"language={lang}",
214+
".",
215+
OUTPUT_DIR / lang,
216+
*session.posargs,
217+
)
218+
219+
220+
@nox.session(name="build-translations")
221+
def build_translations(session):
222+
"""
223+
Build translations of the guide.
224+
225+
Note: this session can be called directly to build all available translations (defined in LANGUAGES).
226+
It is also called by the docs and docs-test sessions with 'release-build' as the first positional
227+
argument, to build only the translations defined in RELEASE_LANGUAGES.
228+
"""
229+
release_build = False
230+
if session.posargs and session.posargs[0] == "release-build":
231+
session.posargs.pop(0)
232+
release_build = True
233+
# if running from the docs or docs-test sessions, build only release languages
234+
BUILD_LANGUAGES = RELEASE_LANGUAGES if release_build else LANGUAGES
235+
# only build languages that have a locale folder
236+
BUILD_LANGUAGES = [
237+
lang
238+
for lang in BUILD_LANGUAGES
239+
if (TRANSLATION_LOCALES_DIR / lang).exists()
240+
]
241+
session.log(f"Declared languages: {LANGUAGES}")
242+
session.log(f"Release languages: {RELEASE_LANGUAGES}")
243+
session.log(
244+
f"Building languages{' for release' if release_build else ''}: {BUILD_LANGUAGES}"
245+
)
246+
if not BUILD_LANGUAGES:
247+
session.warn("No translations to build")
248+
else:
249+
session.notify("build-languages", [BUILD_LANGUAGES, *session.posargs])
250+
251+
252+
@nox.session(name="build-translations-test")
253+
def build_translations_test(session):
254+
"""
255+
Build all translations of the guide with testing parameters.
256+
257+
This is a convenience session to test the build of all translations with the testing parameters
258+
in the same way docs-test does for the English version.
259+
"""
260+
session.notify("build-translations", [*TEST_PARAMETERS])

0 commit comments

Comments
 (0)