Keep versions up to date in the docs (#162)

Instead of hardcoding the version in the documentation, use the new
macro variables to keep the documentation up to date. For examples
showing how to invoke cookiecutter we use the current git reference (tag
or branch) and for `pyproject.toml` dependencies we use a tag if we are
at one, otherwise we use a Git URL pointing to the current branch.

If there is no Git information, we just omit the version, so the latest
version should be used by both.

This PR also fixes a few small issues and prepares for the release.

Fixes #138, refs #134.

Author: llucax

.github/workflows/ci.yaml

@@ -351,6 +351,14 @@ jobs:
           VERSION: ${{ steps.mike-version.outputs.version }}
           TITLE: ${{ steps.mike-version.outputs.title }}
           ALIASES: ${{ steps.mike-version.outputs.aliases }}
+          # This is not ideal, we need to define all these variables here
+          # because we need to calculate all the repository version information
+          # to be able to show the correct versions in the documentation when
+          # building it.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+          GIT_REF: ${{ github.ref }}
+          GIT_SHA: ${{ github.sha }}
         run: |
           mike deploy --update-aliases --title "$TITLE" "$VERSION" $ALIASES
 

CONTRIBUTING.md

@@ -193,3 +193,30 @@ These are the steps to create a new release:
    eventually too).
 
 7. Celebrate!
+
+##  Cross-Arch Testing
+
+This project has built-in support for testing across multiple architectures.
+Currently, our CI conducts tests on `arm64` machines using QEMU emulation. We
+also have the flexibility to expand this support to include additional
+architectures in the future.
+
+This project contains Dockerfiles that can be used in the CI to test the
+python package in non-native machine architectures, e.g., `arm64`. The
+Dockerfiles exist in the directory `.github/containers/nox-cross-arch`, and
+follow a naming scheme so that they can be easily used in build matrices in the
+CI, in `nox-cross-arch` job. The naming scheme is:
+
+```
+<arch>-<os>-python-<python-version>.Dockerfile
+```
+
+E.g.,
+
+```
+arm64-ubuntu-20.04-python-3.11.Dockerfile
+```
+
+If a Dockerfile for your desired target architecture, OS, and python version
+does not exist here, please add one before proceeding to add your options to
+the test matrix.

README.md

@@ -18,7 +18,7 @@ It offers:
 
 ## Supported Platforms
 
-The following platforms are officially supported (test):
+The following platforms are officially supported (tested):
 
 - **Python:** 3.11
 - **Operating System:** Ubuntu Linux 20.04
@@ -31,7 +31,7 @@ Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/installation.html).
 It is normally available in any Linux distribution, but some have a very old
 version (for example, Ubuntu/Debian). You can [check which version your distro
 has on Repology](https://repology.org/project/cookiecutter/versions). You need
-**at least version 2.1.0**. To ensure you get an up-to-date version, you can
+**at least version 2.4.0**. To ensure you get an up-to-date version, you can
 always use `pip` and install it in a `venv`:
 
 ```console
@@ -48,14 +48,17 @@ directory will be created with the generated project name. For example:
 
 ```sh
 cd ~/devel
-cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
-    --directory=cookiecutter \
-    --checkout v0.6.2
+cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter
 ```
 
 This command will prompt you for the project type, name, and other
 configuration options, and it will generate the entire project for you.
 
+It is recommended to use a released version, you can do that by adding the
+option `--checkout <version>` to the command above. You can check which is the
+latest version
+[here](https://github.com/frequenz-floss/frequenz-repo-config-python/releases/latest).
+
 After completing the project and fixing the `TODO`s, you can either amend the
 previous commit using `git commit --amend` or create a new commit for the
 changes using `git commit`.

RELEASE_NOTES.md

@@ -2,14 +2,14 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release focuses on improving the documentation generation and the CI. In particular it brings a new versioning scheme for the documentation that supports multiple development branches and exposes pre-releases.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
-
 ### Cookiecutter template
 
+- The recommended `cookiecutter` version was bumped to 2.4.0 to avoid some buggy old versions.
+
 - `mkdocs`
 
   - The script `docs/mkdocstrings_autoapi.py` was moved to `docs/_scripts/mkdocstrings.py`.
@@ -39,7 +39,13 @@
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+- `frequenz_repo_config.version`: New module to get the version information for a repository.
+- `frequnz_repo_config.github`: New module to interact with GitHub.
+- `frequenz.repo_config.mkdocs.mike`: New module to manage `mike` versions and aliases.
+- `frequenz.repo_config.cli`: New package to implement CLI commands.
+
+  - `frequenz.repo.config.cli.version.mike.info`: New command to print GitHub Action variables with for the current `mike` version.
+  - `frequenz.repo.config.cli.version.mike.sort`: New command to sort `mike` versions file (`versions.json`).
 
 ### Cookiecutter template
 
@@ -51,6 +57,8 @@
   - Make code annotations numbered. This is useful to hint about the order one should read the annotations.
   - Add a navigation footer to show previous and next pages. This is specially useful when reading the documentation in a mobile device since the navigation bar is hidden.
   - Updated dependencies.
+  - The hooking of `mkdocstrings` to `macros` plugins is moved to a separate function to avoid the noise in the `define_env()` function.
+  - Improve formatting of signatures to show the types.
   - We use a new `mike` versioning scheme:
 
     - Versions now have a title with the full tag name for tags and includes the (short) commit SHA for branches so users can know exactly which version they are reading.
@@ -64,9 +72,9 @@
   - Add a CI job to *join* all `nox` runs, so only one branch protection rule needs to be used.
   - Dependabot now will check for updates monthly and on a random day and time. This is to avoid all repositories updating at the same time.
 
-## Bug Fixes
+- Add a section about cross-arch testing to `CONTRIBUTING.md`.
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+## Bug Fixes
 
 ### Cookiecutter template
 

cookiecutter/{{cookiecutter.github_repo_name}}/.github/workflows/ci.yaml

@@ -376,6 +376,14 @@ jobs:
           VERSION: ${{ steps.mike-version.outputs.version }}
           TITLE: ${{ steps.mike-version.outputs.title }}
           ALIASES: ${{ steps.mike-version.outputs.aliases }}
+          # This is not ideal, we need to define all these variables here
+          # because we need to calculate all the repository version information
+          # to be able to show the correct versions in the documentation when
+          # building it.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+          GIT_REF: ${{ github.ref }}
+          GIT_SHA: ${{ github.sha }}
         run: |
           mike deploy --update-aliases --title "$TITLE" "$VERSION" $ALIASES
 

cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

@@ -204,3 +204,30 @@ These are the steps to create a new release:
    eventually too).
 
 7. Celebrate!
+
+##  Cross-Arch Testing
+
+This project has built-in support for testing across multiple architectures.
+Currently, our CI conducts tests on `arm64` machines using QEMU emulation. We
+also have the flexibility to expand this support to include additional
+architectures in the future.
+
+This project contains Dockerfiles that can be used in the CI to test the
+python package in non-native machine architectures, e.g., `arm64`. The
+Dockerfiles exist in the directory `.github/containers/nox-cross-arch`, and
+follow a naming scheme so that they can be easily used in build matrices in the
+CI, in `nox-cross-arch` job. The naming scheme is:
+
+```
+<arch>-<os>-python-<python-version>.Dockerfile
+```
+
+E.g.,
+
+```
+arm64-ubuntu-20.04-python-3.11.Dockerfile
+```
+
+If a Dockerfile for your desired target architecture, OS, and python version
+does not exist here, please add one before proceeding to add your options to
+the test matrix.

cookiecutter/{{cookiecutter.github_repo_name}}/README.md

@@ -12,7 +12,7 @@ TODO(cookiecutter): Improve the README file
 
 ## Supported Platforms
 
-The following platforms are officially supported (test):
+The following platforms are officially supported (tested):
 
 - **Python:** 3.11
 - **Operating System:** Ubuntu Linux 20.04

…ub_repo_name}}/docs/css/mkdocstrings.css …b_repo_name}}/docs/_css/mkdocstrings.csscookiecutter/{{cookiecutter.github_repo_name}}/docs/css/mkdocstrings.css renamed to cookiecutter/{{cookiecutter.github_repo_name}}/docs/_css/mkdocstrings.css cookiecutter/{{cookiecutter.github_repo_name}}/docs/css/mkdocstrings.css renamed to cookiecutter/{{cookiecutter.github_repo_name}}/docs/_css/mkdocstrings.css

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+def _hook_macros_plugin(env: macros.MacrosPlugin) -> None:
+    """Integrate the `mkdocs-macros` plugin into `mkdocstrings`.
+
+    This is a temporary workaround to make `mkdocs-macros` work with
+    `mkdocstrings` until a proper `mkdocs-macros` *pluglet* is available. See
+    https://github.com/mkdocstrings/mkdocstrings/issues/615 for details.
 
     Args:
-        env: The environment to define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # A variable to easily show an example code annotation from mkdocs-material.
-    # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations
-    env.variables["code_annotation_marker"] = _CODE_ANNOTATION_MARKER
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below is a temporary workaround to make `mkdocs-macros` work with
-    # `mkdocstrings` until a proper `mkdocs-macros` *pluglet* is available. See
-    # https://github.com/mkdocstrings/mkdocstrings/issues/615 for details.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # patch the method
     python_handler.update_env = patched_update_env
+
+
+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.
+    """
+    # A variable to easily show an example code annotation from mkdocs-material.
+    # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations
+    env.variables["code_annotation_marker"] = _CODE_ANNOTATION_MARKER
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)