Docs: automatically generate the list of locales (#3272)

docs/dev-guide/translations.md

@@ -213,9 +213,7 @@ Finally, run `mkdocs serve` to check out your new localized version of the theme
 
 ## Updating theme documentation
 
-Update the lists of supported translations for each translated theme located at
-[Choosing your theme](../user-guide/choosing-your-theme.md)
-(`docs/user-guide/choosing-your-theme.md`), in their __`locale`__ options.
+The page [Choosing your theme](../user-guide/choosing-your-theme.md) updates by itself with all available locale options.
 
 ## Contributing translations
 

docs/hooks.py

@@ -0,0 +1,33 @@
+import os.path
+import re
+from pathlib import Path
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.nav import Page
+
+
+def _get_language_of_translation_file(path: Path) -> str:
+    with path.open(encoding='utf-8') as f:
+        translation_line = f.readline()
+    m = re.search('^# (.+) translations ', translation_line)
+    assert m
+    return m[1]
+
+
+def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs):
+    if page.file.src_uri == 'user-guide/choosing-your-theme.md':
+        here = Path(config.config_file_path or '').parent
+
+        def replacement(m: re.Match) -> str:
+            lines = []
+            for d in sorted(here.glob(m[2])):
+                lang = _get_language_of_translation_file(Path(d, 'LC_MESSAGES', 'messages.po'))
+                lines.append(f'{m[1]}`{d.name}`: {lang}')
+            return '\n'.join(lines)
+
+        return re.sub(
+            r'^( *\* )\(see the list of existing directories `(.+)`\)$',
+            replacement,
+            markdown,
+            flags=re.MULTILINE,
+        )

docs/user-guide/choosing-your-theme.md

@@ -108,20 +108,7 @@ supports the following options:
     The following locales are supported by this theme:
 
     * `en`: English (default)
-    * `de`: German
-    * `es`: Spanish
-    * `fa`: Persian (Farsi)
-    * `fr`: French
-    * `id`: Indonesian
-    * `it`: Italian
-    * `ja`: Japanese
-    * `nb`: Norwegian Bokmål
-    * `nn`: Norwegian Nynorsk
-    * `pt_BR`: Portuguese (Brazil)
-    * `ru`: Russian
-    * `tr`: Turkish
-    * `uk`: Ukrainian
-    * `zh_CN`: Simplified Chinese
+    * (see the list of existing directories `mkdocs/themes/mkdocs/locales/*/`)
 
     See the guide on [localizing your theme] for more information.
 
@@ -198,18 +185,7 @@ theme supports the following options:
     The following locales are supported by this theme:
 
     * `en`: English (default)
-    * `de`: German
-    * `es`: Spanish
-    * `fa`: Persian (Farsi)
-    * `fr`: French
-    * `id`: Indonesian
-    * `it`: Italian
-    * `ja`: Japanese
-    * `pt_BR`: Portuguese (Brazil)
-    * `ru`: Russian
-    * `tr`: Turkish
-    * `uk`: Ukrainian
-    * `zh_CN`: Simplified Chinese
+    * (see the list of existing directories `mkdocs/themes/readthedocs/locales/*/`)
 
     See the guide on [localizing your theme] for more information.
 

docs/user-guide/localizing-your-theme.md

@@ -31,8 +31,8 @@ underscore. For example, some possible locales for English might include `en`,
 For a list of locales supported by the theme you are using, see that theme's
 documentation.
 
-- [mkdocs]
-- [readthedocs]
+- [mkdocs](choosing-your-theme.md#mkdocs-locale)
+- [readthedocs](choosing-your-theme.md#readthedocs-locale)
 
 WARNING:
 If you configure a language locale which is not yet supported by the theme
@@ -58,8 +58,6 @@ If a theme has not yet been translated into your language, feel free to
 contribute a translation using the [Translation Guide].
 
 [Translation Guide]: ../dev-guide/translations.md
-[mkdocs]: choosing-your-theme.md#mkdocs-locale
-[readthedocs]: choosing-your-theme.md#readthedocs-locale
 [locale]: configuration.md#locale
 [theme]: configuration.md#theme
 [ISO-639-1]: https://en.wikipedia.org/wiki/ISO_639-1

mkdocs.yml

@@ -46,6 +46,9 @@ markdown_extensions:
 
 copyright: Copyright &copy; 2014 <a href="https://twitter.com/starletdreaming">Tom Christie</a>, Maintained by the <a href="/about/release-notes/#maintenance-team">MkDocs Team</a>.
 
+hooks:
+    - docs/hooks.py
+
 plugins:
     - search
     - redirects:

pyproject.toml

@@ -168,13 +168,13 @@ lint = [
     "flake8 mkdocs",
 ]
 check = [
-    "isort --check-only --diff mkdocs",
-    "black -q --check --diff mkdocs",
+    "isort --check-only --diff mkdocs docs",
+    "black -q --check --diff mkdocs docs",
     "lint",
 ]
 format = [
-    "isort -q mkdocs",
-    "black -q mkdocs",
+    "isort -q mkdocs docs",
+    "black -q mkdocs docs",
 ]
 
 [tool.hatch.envs.lint]