language selector draft :)

Author: sneakers-the-rat

_static/language_select.js

@@ -0,0 +1,13 @@
+document.addEventListener("DOMContentLoaded", () => {
+  let selectors = document.querySelectorAll("#language-selector");
+  selectors.forEach((selector) => {
+    selector.addEventListener("change", (event) => {
+      let target = event.target.value;
+      if (target.startsWith("https")) {
+        window.location.href = target;
+      } else {
+        window.location.pathname = target;
+      }
+    });
+  });
+});

_static/pyos.css

@@ -46,6 +46,10 @@ body {
   margin-right: auto !important;
 }
 
+.navbar-persistent--mobile {
+  margin-left: unset !important;
+}
+
 /* custom fonts */
 
 html,
@@ -375,3 +379,7 @@ th {
   border: 1px solid #ccc; /* Light gray border */
   padding: 8px; /* Add some padding for better readability */
 }
+
+/* ----------------- */
+/* Language Selector */
+/* ----------------- */

_templates/language-selector.html

@@ -0,0 +1,30 @@
+{%- macro langlink(lang, selected=False) -%} {%- if lang == "en" %}
+<option
+  value="{{ baseurl }}{{ pagename }}{{ file_suffix }}"
+  {%
+  if
+  selected
+  %}selected{%
+  endif
+  %}
+>
+  {{ lang }}
+</option>
+{%- else %}
+<option
+  value="{{ baseurl }}{{ lang }}/{{ pagename }}{{ file_suffix }}"
+  {%
+  if
+  selected
+  %}selected{%
+  endif
+  %}
+>
+  {{ lang }}
+</option>
+{%- endif -%} {%- endmacro -%}
+<select class="dropdown" id="language-selector" aria-label="Choose a language">
+  {{ langlink(language, selected=True) }} {%- for a_language in languages -%}
+  {%- if a_language != language -%} {{ langlink(a_language) }} {%- endif -%} {%-
+  endfor %}
+</select>

conf.py

@@ -15,6 +15,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 from datetime import datetime
 import subprocess
+import os
 
 current_year = datetime.now().year
 organization_name = "pyOpenSci"
@@ -26,10 +27,10 @@
 copyright = f"{current_year}, {organization_name}"
 author = "pyOpenSci Community"
 
-language = "en"
-languages = ["es", "jp"]
-# languages excluding english
-# (english is built without a subdirectory to not break already-existing inbound links)
+# 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"]
 
 # Get the latest Git tag - there might be a prettier way to do this but...
 try:
@@ -76,7 +77,11 @@
     {"href": "https://www.pyopensci.org/images/favicon.ico"},
 ]
 
-# Link to our repo for easy PR/ editing
+html_baseurl = "https://www.pyopensci.org/python-package-guide/"
+if os.environ.get("SPHINX_DEV", False):
+    # for links in language selector when developing locally
+    html_baseurl = "/"
+
 html_theme_options = {
     "announcement": "<p><a href='https://www.pyopensci.org/about-peer-review/index.html'>We run peer review of scientific Python software. Learn more.</a></p>",
     # "navbar_center": ["nav"], this can be a way to override the default navigation structure
@@ -116,14 +121,16 @@
     "github_url": "https://github.com/pyopensci/python-package-guide",
     "footer_start": ["code_of_conduct", "copyright"],
     "footer_end": [],
+    "navbar_persistent": ["language-selector", "search-button"]
 }
 
 html_context = {
     "github_user": "pyopensci",
     "github_repo": "python-package-guide",
     "github_version": "main",
-    'language': language,
-    'languages': languages
+    "language": language,
+    "languages": languages,
+    "base_url": html_baseurl,
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -147,7 +154,7 @@
 ]
 
 # For sitemap generation
-html_baseurl = "https://www.pyopensci.org/python-package-guide/"
+
 sitemap_url_scheme = "{link}"
 
 # -- Options for HTML output -------------------------------------------------
@@ -159,7 +166,7 @@
 html_static_path = ["_static"]
 html_css_files = ["pyos.css"]
 html_title = "Python Packaging Guide"
-html_js_files = ["matomo.js"]
+html_js_files = ["matomo.js", "language_select.js"]
 
 
 # Social cards

noxfile.py

@@ -52,7 +52,7 @@
 LANGUAGES = conf.languages
 
 # List of languages that should be built when releasing the guide (docs or docs-test sessions)
-RELEASE_LANGUAGES = []
+RELEASE_LANGUAGES = [lang for lang in conf.languages if lang != "en"]
 
 
 @nox.session
@@ -78,7 +78,7 @@ def docs_test(session):
     session.notify("build-translations", ['release-build', *TEST_PARAMETERS])
 
 def _autobuild_cmd(posargs: list[str], output_dir = OUTPUT_DIR) -> list[str]:
-    cmd = [SPHINX_AUTO_BUILD, *BUILD_PARAMETERS, str(SOURCE_DIR), str(output_dir), *posargs]
+    cmd = ["SPHINX_DEV=true", SPHINX_AUTO_BUILD, *BUILD_PARAMETERS, str(SOURCE_DIR), str(output_dir), *posargs]
     for folder in AUTOBUILD_IGNORE:
         cmd.extend(["--ignore", f"*/{folder}/*"])
     return cmd
@@ -158,8 +158,11 @@ def docs_live_langs(session):
 
     cmds = ['"' + " ".join(_autobuild_cmd(session.posargs) + ['--open-browser']) + '"']
     for language in LANGUAGES:
+        if language == "en":
+            continue
         cmds.append(
             '"' + " ".join(
+                [f"SPHINX_LANG={language}"] +
                 _autobuild_cmd(
                     session.posargs + ["-D", f"language={language}"],
                     output_dir=OUTPUT_DIR / language
@@ -217,7 +220,11 @@ def build_languages(session):
             session.warn(f"Language [{lang}] is not available for translation")
             continue
         session.log(f"Building [{lang}] guide")
-        session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs)
+        if lang == 'en':
+            out_dir = OUTPUT_DIR
+        else:
+            out_dir = OUTPUT_DIR / lang
+        session.run(f"SPHINX_LANG={lang}", SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", out_dir, *session.posargs)
 
 
 @nox.session(name="build-translations")