Add mkdocs-macros plugin (#667)

This plugin allow us to avoid repetition by defining variables that can
be used throughout the documentation or even functions to automate
certain things.

Also add a mkdocs macro to link to the glossary. Documentation in both
`docs/` or the code can link to glossary terms by just using
`{{glossary("Term")}}`.

Author: llucax

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)})"

docs/mkdocstrings_autoapi.py docs/_scripts/mkdocstrings_autoapi.pydocs/mkdocstrings_autoapi.py renamed to docs/_scripts/mkdocstrings_autoapi.py

@@ -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
->>> 
+>>>
 ```

docs/index.md

@@ -85,9 +85,13 @@ markdown_extensions:
 plugins:
   - gen-files:
       scripts:
-        - docs/mkdocstrings_autoapi.py
+        - docs/_scripts/mkdocstrings_autoapi.py
   - literate-nav:
       nav_file: SUMMARY.md
+  - macros:
+      module_name: docs/_scripts/macros
+      on_undefined: strict
+      on_error_fail: true
   - mike:
       canonical_version: latest
   - mkdocstrings:
@@ -120,5 +124,4 @@ plugins:
 # Preview controls
 watch:
   - "src"
-  - README.md
   - CONTRIBUTING.md

mkdocs.yml

@@ -62,8 +62,8 @@ 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",
   "frequenz-repo-config[lib] == 0.6.1",
 ]
@@ -176,6 +176,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",