unify dev/prod switching into SPHINX_ENV, fix jp -> ja language name, separate build_languages from languages in conf.py

Author: sneakers-the-rat

README.md

@@ -58,6 +58,28 @@ To build live documentation that updates when you update local files, run the fo
 $ nox -s docs-live
 ```
 
+### Building for release
+
+When building for release, the docs are built multiple times for each translation,
+but translations are only included in the production version of the guide after some completion threshold.
+
+The sphinx build environment is controlled by an environment variable `SPHINX_ENV`
+
+- when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
+  and includes them in the language selector
+- when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
+  are built and included in the language selector.
+
+Most of the time you should not need to set `SPHINX_ENV`,
+as it is forced by the primary nox sessions intended to be used for release or development:
+
+`SPHINX_ENV=development`
+- `docs-live` - autobuild english
+- `docs-live-lang` - autobuild a single language
+- `docs-live-langs` - autobuild all languages
+
+`SPHINX_ENV=production`
+- `build-test` - build all languages for production
 
 ## Contributing to this guide
 

conf.py

@@ -20,17 +20,34 @@
 current_year = datetime.now().year
 organization_name = "pyOpenSci"
 
+# env vars
+sphinx_env = os.environ.get("SPHINX_ENV", "development")
+language_env = os.environ.get("SPHINX_LANG", "en")
+
 
 # -- Project information -----------------------------------------------------
 
 project = "pyOpenSci Python Package Guide"
 copyright = f"{current_year}, {organization_name}"
 author = "pyOpenSci Community"
 
+# Language of the current build
 # language can later be overridden (eg with the -D flag)
 # but we need it set here so it can make it into the html_context
-language = os.environ.get("SPHINX_LANG", "en")
-languages = ["en", "es", "jp"]
+language = language_env
+# all languages that have .po files generated for them
+# (excluding english)
+languages = ["es", "ja"]
+# the languages that will be included in a production build
+# (also excluding english)
+release_languages = []
+
+# languages that will be included in the language dropdown
+# (ie. all that are being built in this nox build session)
+if sphinx_env == "production":
+    build_languages = ["en"] + release_languages
+else:
+    build_languages = ["en"] + languages
 
 # Get the latest Git tag - there might be a prettier way to do this but...
 try:
@@ -78,7 +95,7 @@
 ]
 
 html_baseurl = "https://www.pyopensci.org/python-package-guide/"
-if os.environ.get("SPHINX_DEV", False):
+if not sphinx_env == "production":
     # for links in language selector when developing locally
     html_baseurl = "/"
 
@@ -129,8 +146,8 @@
     "github_repo": "python-package-guide",
     "github_version": "main",
     "language": language,
-    "languages": languages,
-    "base_url": html_baseurl,
+    "languages": build_languages,
+    "baseurl": html_baseurl,
 }
 
 # Add any paths that contain templates here, relative to this directory.

noxfile.py

@@ -52,16 +52,19 @@
 LANGUAGES = conf.languages
 
 # List of languages that should be built when releasing the guide (docs or docs-test sessions)
-RELEASE_LANGUAGES = [lang for lang in conf.languages if lang != "en"]
+RELEASE_LANGUAGES = conf.release_languages
 
+# allowable values of `SPHINX_ENV`
+SPHINX_ENVS = ('production', 'development')
 
 @nox.session
 def docs(session):
     """Build the packaging guide."""
     session.install("-e", ".")
+    sphinx_env = _sphinx_env(session)
     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-translations", [sphinx_env])
 
 
 @nox.session(name="docs-test")
@@ -72,13 +75,14 @@ def docs_test(session):
     Note: this is the session used in CI/CD to release the guide.
     """
     session.install("-e", ".")
-    session.run(SPHINX_BUILD, *BUILD_PARAMETERS, *TEST_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs)
+    session.run(SPHINX_BUILD, *BUILD_PARAMETERS, *TEST_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs,
+                env={'SPHINX_ENV': 'production'})
     # 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-translations", ['production', *TEST_PARAMETERS])
 
 def _autobuild_cmd(posargs: list[str], output_dir = OUTPUT_DIR) -> list[str]:
-    cmd = ["SPHINX_DEV=true", SPHINX_AUTO_BUILD, *BUILD_PARAMETERS, str(SOURCE_DIR), str(output_dir), *posargs]
+    cmd = [SPHINX_AUTO_BUILD, *BUILD_PARAMETERS, str(SOURCE_DIR), str(output_dir), *posargs]
     for folder in AUTOBUILD_IGNORE:
         cmd.extend(["--ignore", f"*/{folder}/*"])
     return cmd
@@ -104,7 +108,7 @@ def docs_live(session):
     # This part was commented in the previous version of the nox file, keeping the same here
     # for folder in AUTOBUILD_INCLUDE:
     #     cmd.extend(["--watch", folder])
-    session.run(*cmd)
+    session.run(*cmd, env={'SPHINX_ENV': "development"})
 
 
 @nox.session(name="docs-live-lang")
@@ -156,20 +160,18 @@ def docs_live_langs(session):
 
     session.install("-e", ".")
 
-    cmds = ['"' + " ".join(_autobuild_cmd(session.posargs) + ['--open-browser']) + '"']
+    cmds = ['"' + " ".join(["SPHINX_ENV=development"] + _autobuild_cmd(session.posargs) + ['--open-browser']) + '"']
     for language in LANGUAGES:
-        if language == "en":
-            continue
         cmds.append(
             '"' + " ".join(
-                [f"SPHINX_LANG={language}"] +
+                [f"SPHINX_LANG={language}", "SPHINX_ENV=development"] +
                 _autobuild_cmd(
                     session.posargs + ["-D", f"language={language}"],
                     output_dir=OUTPUT_DIR / language
                 ) + ["--port=0"]
             ) + '"'
         )
-    cmd = ['concurrently', '--kill-others', '-n', ','.join(LANGUAGES), '-c', 'auto', *cmds]
+    cmd = ['concurrently', '--kill-others', '-n', ','.join(["en"] + LANGUAGES), '-c', 'auto', *cmds]
     session.run(*cmd)
 
 @nox.session(name="docs-clean")
@@ -212,6 +214,9 @@ def build_languages(session):
     """
     if not session.posargs:
         session.error("Please provide the list of languages to build the translation for")
+
+    sphinx_env = _sphinx_env(session)
+
     languages_to_build = session.posargs.pop(0)
 
     session.install("-e", ".")
@@ -224,7 +229,8 @@ def build_languages(session):
             out_dir = OUTPUT_DIR
         else:
             out_dir = OUTPUT_DIR / lang
-        session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", out_dir, *session.posargs, env={"SPHINX_LANG": lang})
+        session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", out_dir, *session.posargs,
+                    env={"SPHINX_LANG": lang, "SPHINX_ENV": sphinx_env})
 
 
 @nox.session(name="build-translations")
@@ -236,21 +242,19 @@ def build_translations(session):
     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.
     """
-    release_build = False
-    if session.posargs and session.posargs[0] == 'release-build':
-        session.posargs.pop(0)
-        release_build = True
+    sphinx_env = _sphinx_env(session)
+
     # if running from the docs or docs-test sessions, build only release languages
-    BUILD_LANGUAGES = RELEASE_LANGUAGES if release_build else LANGUAGES
+    BUILD_LANGUAGES = RELEASE_LANGUAGES if sphinx_env == "production" 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}")
+    session.log(f"Building languages{' for release' if sphinx_env == 'production' else ''}: {BUILD_LANGUAGES}")
     if not BUILD_LANGUAGES:
         session.warn("No translations to build")
     else:
-        session.notify("build-languages", [BUILD_LANGUAGES, *session.posargs])
+        session.notify("build-languages", [sphinx_env, BUILD_LANGUAGES, *session.posargs])
 
 
 @nox.session(name="build-translations-test")
@@ -262,3 +266,14 @@ def build_translations_test(session):
     in the same way docs-test does for the English version.
     """
     session.notify("build-translations", [*TEST_PARAMETERS])
+
+
+def _sphinx_env(session) -> str:
+    """
+    Get the sphinx env, from the first positional argument if present or from the
+    ``SPHINX_ENV`` environment variable, defaulting to "development"
+    """
+    if session.posargs and session.posargs[0] in SPHINX_ENVS:
+        return session.posargs.pop(0)
+    else:
+        return os.environ.get('SPHINX_ENV', 'development')