From b162c5e824592a5acd94d18fa65ad47d3f2cf198 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Fri, 23 Jun 2023 09:35:26 +0200 Subject: [PATCH] Docs: automatically generate the list of locales (#3272) --- docs/dev-guide/translations.md | 4 +-- docs/hooks.py | 33 ++++++++++++++++++++++++ docs/user-guide/choosing-your-theme.md | 28 ++------------------ docs/user-guide/localizing-your-theme.md | 6 ++--- mkdocs.yml | 3 +++ pyproject.toml | 8 +++--- 6 files changed, 45 insertions(+), 37 deletions(-) create mode 100644 docs/hooks.py diff --git a/docs/dev-guide/translations.md b/docs/dev-guide/translations.md index 80df04b5..ea3e5a87 100644 --- a/docs/dev-guide/translations.md +++ b/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 diff --git a/docs/hooks.py b/docs/hooks.py new file mode 100644 index 00000000..1ab58b88 --- /dev/null +++ b/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, + ) diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index 58a738c9..ea7da128 100644 --- a/docs/user-guide/choosing-your-theme.md +++ b/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. diff --git a/docs/user-guide/localizing-your-theme.md b/docs/user-guide/localizing-your-theme.md index f6de982e..ae0e7baf 100644 --- a/docs/user-guide/localizing-your-theme.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index b0129746..a3ed5a5c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,6 +46,9 @@ markdown_extensions: copyright: Copyright © 2014 Tom Christie, Maintained by the MkDocs Team. +hooks: + - docs/hooks.py + plugins: - search - redirects: diff --git a/pyproject.toml b/pyproject.toml index e76ca8a9..4a3def01 100644 --- a/pyproject.toml +++ b/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]