From 0eddb126030cb03550ca2ebc119578010d5f241a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Tue, 19 May 2026 19:30:56 +0200
Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Refactor=20MkDocs=20to=20Z?=
 =?UTF-8?q?ensical=20logic?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/build-docs.yml |  5 ++-
 scripts/docs.py                  | 70 +++++++++++---------------------
 2 files changed, 28 insertions(+), 47 deletions(-)

diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index f7d499cc05..e56953da3e 100644
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -40,6 +40,7 @@ jobs:
   langs:
     needs:
       - changes
+    if: ${{ needs.changes.outputs.docs == 'true' }}
     runs-on: ubuntu-latest
     outputs:
       langs: ${{ steps.show-langs.outputs.langs }}
@@ -105,10 +106,12 @@ jobs:
           path: site_zensical_src/${{ matrix.lang }}/.cache
       - name: Build Docs
         run: | # zizmor: ignore[template-injection] - comes from trusted source
-          uv run ./scripts/docs.py build-zensical-lang ${{ matrix.lang }}
+          uv run ./scripts/docs.py build-lang ${{ matrix.lang }}
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: docs-site-${{ matrix.lang }}
+          # English owns root static assets. Translated pages reference /img, /css,
+          # and /js, so omit duplicated language-local copies from artifacts.
           path: |
             ./site/**
             !./site/${{ matrix.lang }}/img/**
diff --git a/scripts/docs.py b/scripts/docs.py
index 5c08ca3d33..a273cab2f8 100644
--- a/scripts/docs.py
+++ b/scripts/docs.py
@@ -150,9 +150,11 @@ def build_lang(
     ),
 ) -> None:
     """
-    Build the Zensical docs for a language.
+    Build the docs for a language.
     """
-    build_zensical_lang(lang)
+    build_zensical_lang_to_stage(lang)
+    copy_zensical_stage_to_site(lang)
+    typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)
 
 
 def split_markdown_header(markdown: str) -> tuple[str, str]:
@@ -304,48 +306,6 @@ def copy_zensical_stage_to_site(lang: str) -> None:
     shutil.copytree(build_site_dist_path, dist_path, dirs_exist_ok=True)
 
 
-@app.command()
-def build_zensical_lang(
-    lang: str = typer.Argument(
-        ..., callback=lang_callback, autocompletion=complete_existing_lang
-    ),
-) -> None:
-    """
-    Build the docs for a language with Zensical using staged sources.
-    """
-    build_zensical_lang_to_stage(lang)
-    copy_zensical_stage_to_site(lang)
-    typer.secho(
-        f"Successfully built Zensical docs for: {lang}", color=typer.colors.GREEN
-    )
-
-
-@app.command()
-def build_zensical_all() -> None:
-    """
-    Build the full translated docs site with Zensical into ./site/.
-    """
-    update_languages()
-    shutil.rmtree(site_path, ignore_errors=True)
-    shutil.rmtree(zensical_src_path, ignore_errors=True)
-    shutil.copytree(Path("docs_src"), zensical_src_path / "docs_src")
-    langs = [
-        lang.name
-        for lang in get_lang_paths()
-        if (lang.is_dir() and lang.name in SUPPORTED_LANGS)
-    ]
-    process_pool_size = min(4, len(langs), os.cpu_count() or 1)
-    typer.echo(f"Using process pool size: {process_pool_size}")
-    with Pool(process_pool_size) as p:
-        p.map(build_zensical_lang_to_stage, langs)
-    if "en" in langs:
-        copy_zensical_stage_to_site("en")
-    for lang in langs:
-        if lang != "en":
-            copy_zensical_stage_to_site(lang)
-    typer.secho("Successfully built all Zensical docs", color=typer.colors.GREEN)
-
-
 index_sponsors_template = """
 ### Keystone Sponsor
 
@@ -427,9 +387,27 @@ def generate_readme() -> None:
 @app.command()
 def build_all() -> None:
     """
-    Build the full translated docs site with Zensical into ./site/.
+    Build the full translated docs site into ./site/.
     """
-    build_zensical_all()
+    update_languages()
+    shutil.rmtree(site_path, ignore_errors=True)
+    shutil.rmtree(zensical_src_path, ignore_errors=True)
+    shutil.copytree(Path("docs_src"), zensical_src_path / "docs_src")
+    langs = [
+        lang.name
+        for lang in get_lang_paths()
+        if (lang.is_dir() and lang.name in SUPPORTED_LANGS)
+    ]
+    process_pool_size = min(4, len(langs), os.cpu_count() or 1)
+    typer.echo(f"Using process pool size: {process_pool_size}")
+    with Pool(process_pool_size) as p:
+        p.map(build_zensical_lang_to_stage, langs)
+    if "en" in langs:
+        copy_zensical_stage_to_site("en")
+    for lang in langs:
+        if lang != "en":
+            copy_zensical_stage_to_site(lang)
+    typer.secho("Successfully built all docs", color=typer.colors.GREEN)
 
 
 @app.command()