Rename translation session in noxfile.py

Author: flpm

noxfile.py

@@ -55,7 +55,7 @@ def docs(session):
     session.install("-e", ".")
     session.run(SPHINX_BUILD, *BUILD_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs)
     # When building the guide, also build the translations in RELEASE_LANGUAGES
-    session.notify("build-translations", ['release-build'])
+    session.notify("build-release-languages", session.posargs)
 
 
 @nox.session(name="docs-test")
@@ -69,7 +69,7 @@ def docs_test(session):
     session.run(SPHINX_BUILD, *BUILD_PARAMETERS, *TEST_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs)
     # When building the guide with additional parameters, also build the translations in RELEASE_LANGUAGES
     # with those same parameters.
-    session.notify("build-translations", ['release-build', *TEST_PARAMETERS])
+    session.notify("build-release-languages", [*TEST_PARAMETERS, *session.posargs])
 
 
 @nox.session(name="docs-live")
@@ -142,8 +142,8 @@ def clean_dir(session):
             pathlib.Path(content).unlink()
 
 
-@nox.session(name="update-translations")
-def update_translations(session):
+@nox.session(name="update-release-languages")
+def update_release_languages(session):
     """
     Update the translation files (./locales/*/.po) for languages in RELEASE_LANGUAGES.
 
@@ -189,60 +189,63 @@ def update_language(session):
             f" where LANG is one of: {LANGUAGES}"
         )
 
-
-@nox.session(name="build-languages")
-def build_languages(session):
+@nox.session(name="build-language")
+def build_language(session):
     """
-    Build the translations of the guide for the specified language.
+    Build the guide for a specific language translation
 
-    Note: This sessions expects a list of languages to build in the first position of the session arguments.
-    It does not need to be called directly, it is started by build_translations session.
+    For example: nox -s build-language -- es.
     """
-    if not session.posargs:
-        session.error("Please provide the list of languages to build the translation for")
-    languages_to_build = session.posargs.pop(0)
+    if session.posargs and (lang := session.posargs.pop(0)):
+        if lang in LANGUAGES:
+            session.install("-e", ".")
+            session.log(f"Building [{lang}] guide")
+            session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs)
+        else:
+            session.error(f"Language {lang} is not in LANGUAGES list.")
+    else:
+        session.error(
+            "Please provide a language using:\n\n      "
+            "nox -s build-language -- LANG\n\n     "
+            f" where LANG is one of: {LANGUAGES}"
+        )
 
+
+@nox.session(name="build-release-languages")
+def build_release_languages(session):
+    """
+    Build the translations of the guide for the languages in RELEASE_LANGUAGES.
+    """
+    if not RELEASE_LANGUAGES:
+        session.warn("No release languages defined in RELEASE_LANGUAGES")
+        return
     session.install("-e", ".")
-    for lang in languages_to_build:
-        if lang not in LANGUAGES:
-            session.warn(f"Language [{lang}] is not available for translation")
-            continue
+    for lang in RELEASE_LANGUAGES:
         session.log(f"Building [{lang}] guide")
         session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs)
+    session.log(f"Translations built for {RELEASE_LANGUAGES}")
 
-
-@nox.session(name="build-translations")
-def build_translations(session):
+@nox.session(name="build-all-languages")
+def build_all_languages(session):
     """
-    Build translations of the guide.
-
-    Note: this session can be called directly to build all available translations (defined in LANGUAGES).
-    It is also called by the docs and docs-test sessions with 'release-build' as the first positional
-    argument, to build only the translations defined in RELEASE_LANGUAGES.
+    Build the translations of the guide for the languages in LANGUAGES.
     """
-    release_build = False
-    if session.posargs and session.posargs[0] == 'release-build':
-        session.posargs.pop(0)
-        release_build = True
-    # if running from the docs or docs-test sessions, build only release languages
-    BUILD_LANGUAGES = RELEASE_LANGUAGES if release_build else LANGUAGES
-    # only build languages that have a locale folder
-    BUILD_LANGUAGES = [lang for lang in BUILD_LANGUAGES if (TRANSLATION_LOCALES_DIR / lang).exists()]
-    session.log(f"Declared languages: {LANGUAGES}")
-    session.log(f"Release languages: {RELEASE_LANGUAGES}")
-    session.log(f"Building languages{' for release' if release_build else ''}: {BUILD_LANGUAGES}")
-    if not BUILD_LANGUAGES:
-        session.warn("No translations to build")
-    else:
-        session.notify("build-languages", [BUILD_LANGUAGES, *session.posargs])
+    if not LANGUAGES:
+        session.warn("No languages defined in LANGUAGES")
+        return
+    session.install("-e", ".")
+    for lang in LANGUAGES:
+        session.log(f"Building [{lang}] guide")
+        session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs)
+    session.log(f"Translations built for {LANGUAGES}")
 
 
-@nox.session(name="build-translations-test")
-def build_translations_test(session):
+@nox.session(name="build-all-languages-test")
+def build_all_languages_test(session):
     """
-    Build all translations of the guide with testing parameters.
+    Build all translations of the guide with the testing parameters.
 
     This is a convenience session to test the build of all translations with the testing parameters
     in the same way docs-test does for the English version.
     """
-    session.notify("build-translations", [*TEST_PARAMETERS])
+    session.notify("build-all-languages", [*TEST_PARAMETERS])