From 412c55c845428e3881fe07ff449678a330c01907 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Wed, 13 Sep 2023 17:17:35 +0200 Subject: [PATCH 1/7] Add mkdocs-macros plugin This plugin allow us to avoid repetition by defining variables that can be used throughout the documentation or even functions to automate certain things. Signed-off-by: Leandro Lucarella --- mkdocs.yml | 3 +++ pyproject.toml | 1 + 2 files changed, 4 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index c86bb14ae..9300b2ccc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,6 +88,9 @@ plugins: - docs/mkdocstrings_autoapi.py - literate-nav: nav_file: SUMMARY.md + - macros: + on_undefined: strict + on_error_fail: true - mike: canonical_version: latest - mkdocstrings: diff --git a/pyproject.toml b/pyproject.toml index 78d506c58..789ecacfd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -62,6 +62,7 @@ dev-mkdocs = [ "mike == 1.1.2", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", + "mkdocs-macros-plugin == 1.0.4", "mkdocs-material == 9.3.1", "mkdocs-section-index == 0.3.7", "mkdocstrings[python] == 0.23.0", From 50961ba50ccc0f89861ccc19df66e4942117d6ef Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Wed, 13 Sep 2023 17:19:12 +0200 Subject: [PATCH 2/7] Add a mkdocs macro to link to the glossary Now documentation, both in `docs/` or in the code, can link to glossary terms by just using `{{glossary("Term")}}`. Signed-off-by: Leandro Lucarella --- docs/_scripts/macros.py | 46 +++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + pyproject.toml | 1 + 3 files changed, 48 insertions(+) create mode 100644 docs/_scripts/macros.py diff --git a/docs/_scripts/macros.py b/docs/_scripts/macros.py new file mode 100644 index 000000000..3ba14eb54 --- /dev/null +++ b/docs/_scripts/macros.py @@ -0,0 +1,46 @@ +# License: MIT +# Copyright © 2023 Frequenz Energy-as-a-Service GmbH + +"""This module defines macros for use in Markdown files.""" + +import pathlib + +from markdown.extensions import toc +from mkdocs_macros import plugin as macros + + +def define_env(env: macros.MacrosPlugin) -> None: + """Define the hook to create macro functions for use in Markdown. + + Args: + env: The environment to define the macro functions in. + """ + + def _slugify(text: str) -> str: + """Slugify a text. + + Args: + text: The text to slugify. + + Returns: + The slugified text. + """ + # The type of the return value is not defined for the markdown library. + # Also for some reason `mypy` thinks the `toc` module doesn't have a + # `slugify_unicode` function, but it definitely does. + return toc.slugify_unicode(text, "-") # type: ignore[attr-defined,no-any-return] + + @env.macro # type: ignore[misc] + def glossary(term: str) -> str: + """Create a link to the glossary entry for the given term. + + Args: + term: The term to link to. + + Returns: + The Markdown link to the glossary entry for the given term. + """ + current_path = pathlib.Path(env.page.file.src_uri) + glossary_path = pathlib.Path("intro/glossary.md") + link_path = glossary_path.relative_to(current_path.parent) + return f"[{term}]({link_path}#{_slugify(term)})" diff --git a/mkdocs.yml b/mkdocs.yml index 9300b2ccc..d5f608ef4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,6 +89,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - macros: + module_name: docs/_scripts/macros on_undefined: strict on_error_fail: true - mike: diff --git a/pyproject.toml b/pyproject.toml index 789ecacfd..1dfdd7dd4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -177,6 +177,7 @@ module = [ "async_solipsism.*", "grpc.aio", "grpc.aio.*", + "mkdocs_macros.*", # There is a stubs package available, but it's not working: # https://github.com/eggplants/networkx-stubs/issues/1 "networkx", From fe4841cbd53e37d9d39b1956addcc90181dc83ff Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Wed, 13 Sep 2023 17:24:57 +0200 Subject: [PATCH 3/7] Move `mkdocstrings_autoapi.py` to `docs/_scripts` Signed-off-by: Leandro Lucarella --- docs/{ => _scripts}/mkdocstrings_autoapi.py | 0 mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{ => _scripts}/mkdocstrings_autoapi.py (100%) diff --git a/docs/mkdocstrings_autoapi.py b/docs/_scripts/mkdocstrings_autoapi.py similarity index 100% rename from docs/mkdocstrings_autoapi.py rename to docs/_scripts/mkdocstrings_autoapi.py diff --git a/mkdocs.yml b/mkdocs.yml index d5f608ef4..c46f7741b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,7 +85,7 @@ markdown_extensions: plugins: - gen-files: scripts: - - docs/mkdocstrings_autoapi.py + - docs/_scripts/mkdocstrings_autoapi.py - literate-nav: nav_file: SUMMARY.md - macros: From a89b28df4e315c2996d698bb5b200c1515eade21 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Wed, 13 Sep 2023 17:28:21 +0200 Subject: [PATCH 4/7] Sort `mkdocs.yml` `watch` section Signed-off-by: Leandro Lucarella --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index c46f7741b..86db24363 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -124,5 +124,5 @@ plugins: # Preview controls watch: - "src" - - README.md - CONTRIBUTING.md + - README.md From 1abf6b22160d44c707745f195f0a722666cabc6c Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 18 Sep 2023 15:11:49 +0200 Subject: [PATCH 5/7] Remove unused `mkdocs-section-index` package A built-in feature of `mkdocs-material` is used instead. Signed-off-by: Leandro Lucarella --- pyproject.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 1dfdd7dd4..3b8ee35bd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,7 +64,6 @@ dev-mkdocs = [ "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", "mkdocs-material == 9.3.1", - "mkdocs-section-index == 0.3.7", "mkdocstrings[python] == 0.23.0", "frequenz-repo-config[lib] == 0.6.1", ] From 634cd50d220f4695a886283b5ff761f655d00f88 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 18 Sep 2023 11:02:02 +0200 Subject: [PATCH 6/7] mkdocs: Don't watch the README.md file anymore The README.md file is not included in the documentation anymore, so there is no need to watch it for changes. Signed-off-by: Leandro Lucarella --- mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 86db24363..81196434a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -125,4 +125,3 @@ plugins: watch: - "src" - CONTRIBUTING.md - - README.md From 6c066a4a7b3408aed76df39b3bcbeab224b92a2c Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 18 Sep 2023 15:41:09 +0200 Subject: [PATCH 7/7] Add a link to the official pip installation instructions `pip` doesn't come installed by default in some systems, so it's better to link to the official instructions to install it. Signed-off-by: Leandro Lucarella --- docs/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 00ff97e72..cf879f40f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,7 +49,9 @@ python3 -m venv .venv This will create the virtual environment and activate it automatically for you. -Now you can install the SDK by using `pip`: +Now you can install the SDK by using `pip` (if you don't have `pip` installed +you can follow [the official +instructions](https://pip.pypa.io/en/stable/installation/)): ```sh python3 -m pip install frequenz-sdk @@ -63,5 +65,5 @@ $ python3 Python 3.11.4 (main, Jun 7 2023, 10:13:09) [GCC 12.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import frequenz.sdk ->>> +>>> ```