Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: change update translation sessions in nox #398

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

docs: change update translation sessions in nox #398

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
10c57ad
Fix missing quote in documentation.po file
flpm Aug 27, 2024
5139bc7
Modified update-translations to include only RELEASE_LANGUAGES; added…
flpm Aug 27, 2024
a2a73c4
Rename translation session in noxfile.py
flpm Aug 29, 2024
935083a
Merge branch 'main' into change-update-translations
tkoyama010 Aug 29, 2024
2a9d1f8
Merge branch 'main' into change-update-translations
flpm Sep 10, 2024
f95651e
Merge branch 'main' into change-update-translations
flpm Sep 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 87 additions & 53 deletions noxfile.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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")
Expand Down Expand Up @@ -142,76 +142,110 @@ 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 all languages translations.
Update the translation files (./locales/*/.po) for languages in RELEASE_LANGUAGES.

Note: this step is important because it makes sure that the translation files are
up to date with the latest changes in the guide.
Note: this step is called in the CI to keep release translations up to date with
the latest changes in the guide.
"""
session.install("-e", ".")
session.install("sphinx-intl")
session.log("Updating templates (.pot)")
session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs)
for lang in LANGUAGES:
session.log(f"Updating .po files for [{lang}] translation")
session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang)
if RELEASE_LANGUAGES:
session.install("-e", ".")
session.install("sphinx-intl")
session.log("Updating templates (.pot)")
session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs)
for lang in RELEASE_LANGUAGES:
session.log(f"Updating .po files for [{lang}] translation")
session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang)
else:
session.warn("No release languages defined in RELEASE_LANGUAGES")


@nox.session(name="build-languages")
def build_languages(session):
@nox.session(name="update-language")
def update_language(session):
"""
Build the translations of the guide for the specified language.
Update the translation files (./locales/*/.po) 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.
Note: this step is used by language coordinators to keep their translation files up to date
with the latest changes in the guide, before the translation is released.
"""
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.install("sphinx-intl")
session.log("Updating templates (.pot)")
session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs)
session.log(f"Updating .po files for [{lang}] translation")
session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang)
else:
f"[{lang}] locale is not available. Try using:\n\n "
"nox -s docs-live-lang -- LANG\n\n "
f"where LANG is one of: {LANGUAGES}"
else:
session.error(
"Please provide a language using:\n\n "
"nox -s update-language -- LANG\n\n "
f" where LANG is one of: {LANGUAGES}"
)

@nox.session(name="build-language")
def build_language(session):
"""
Build the guide for a specific language translation

For example: nox -s build-language -- es.
"""
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])
Loading