Update to repo-config v0.7.4 (#752)

llucax · web-flow · commit 0e69660e5d83 · 2023-11-03T12:15:34.000Z
The summary of changes is:

- Add some missing copyright notices.
- Update dependencies monthly instead of weekly.
- Move some support files for the documentation website to names
starting with `_` to make it more clear they are only support files.
- Fix the CI to ignore dependabot pushes (they are tested via the PR).
- Use the new documentation website versioning scheme. This means now
multiple development branches are exposed, as well as pre-releases. Also
the order of the versions is improved. The `next` version is replaced by
the multiple `vX.Y-dev` versions.
- Unify formatting in the README.
- Move the hack to integrate `mkdocs` `macros` and `mkdocstrings`
plugins into its own function.
- Add a few handy `mkdocs`/`markdown` extensions.
- Unify some `pyproject.toml` options.
- Remove customizations in the `noxfile.py` as now `repo-config` can
handle it natively.
- Remove unnecessary fields from the cookiecutter replay file.
diff --git a/.cookiecutter-replay.json b/.cookiecutter-replay.json
@@ -13,7 +13,6 @@
     "python_package": "frequenz.sdk",
     "pypi_package_name": "frequenz-sdk",
     "github_repo_name": "frequenz-sdk-python",
-    "default_codeowners": "@frequenz-floss/python-sdk-team",
-    "_template": "gh:frequenz-floss/frequenz-repo-config-python"
+    "default_codeowners": "@frequenz-floss/python-sdk-team"
   }
 }
diff --git a/.github/containers/nox-cross-arch/arm64-ubuntu-20.04-python-3.11.Dockerfile b/.github/containers/nox-cross-arch/arm64-ubuntu-20.04-python-3.11.Dockerfile
@@ -1,3 +1,8 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+# This Dockerfile is used to run the tests in arm64, which is not supported by
+# GitHub Actions at the moment.
+
 FROM docker.io/library/ubuntu:20.04
 
 ENV DEBIAN_FRONTEND=noninteractive
diff --git a/.github/containers/nox-cross-arch/entrypoint.bash b/.github/containers/nox-cross-arch/entrypoint.bash
@@ -1,4 +1,6 @@
 #!/bin/bash
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 set -e
 
 echo "System details:" $(uname -a)
diff --git a/.github/containers/test-installation/Dockerfile b/.github/containers/test-installation/Dockerfile
@@ -1,4 +1,6 @@
-# This dockerfile is used to test the installation of the python package in
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+# This Dockerfile is used to test the installation of the python package in
 # multiple platforms in the CI. It is not used to build the package itself.
 
 FROM --platform=${TARGETPLATFORM} python:3.11-slim
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -3,8 +3,8 @@ updates:
   - package-ecosystem: "pip"
     directory: "/"
     schedule:
-      interval: "weekly"
-      time: "07:00"
+      interval: "monthly"
+      day: "friday"
     labels:
       - "part:tooling"
       - "type:tech-debt"
@@ -34,8 +34,8 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
-      time: "06:00"
+      interval: "monthly"
+      day: "friday"
     labels:
       - "part:tooling"
       - "type:tech-debt"
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -45,7 +45,7 @@
   - ".editorconfig"
   - ".git*"
   - ".git*/**"
-  - "docs/**/*.py"
+  - "docs/*.py"
   - CODEOWNERS
   - MANIFEST.in
   - noxfile.py
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -13,6 +13,7 @@ on:
       # We only want to test the merge commit (`merge_group` event), the hashes
       # in the push were already tested by the PR checks
       - 'gh-readonly-queue/**'
+      - 'dependabot/**'
   workflow_dispatch:
 
 env:
@@ -307,78 +308,68 @@ jobs:
     permissions:
       contents: write
     steps:
-      - name: Calculate and check version
-        id: mike-metadata
-        env:
-          REF: ${{ github.ref }}
-          REF_NAME: ${{ github.ref_name }}
-          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
-        run: |
-          aliases=
-          version=
-          if test "$REF_NAME" = "$DEFAULT_BRANCH"
-          then
-            version=next
-          # A tag that starts with vX.Y or X.Y
-          elif echo "$REF" | grep -q '^refs/tags' && echo "$REF_NAME" | grep -Pq '^v?\d+\.\d+\.'
-          then
-            if echo "$REF_NAME" | grep -Pq -- "-" # pre-release
-            then
-              echo "::notice title=Documentation was not published::" \
-                "The tag '$REF_NAME' looks like a pre-release."
-              exit 0
-            fi
-            version=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+\.[0-9]+)\..*$/\1/') # vX.Y
-            major=$(echo "$REF_NAME" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
-            default_major=$(echo "$DEFAULT_BRANCH" | sed -r 's/^(v?[0-9]+)\..*$/\1/') # vX
-            aliases=$major
-            if test "$major" = "$default_major"
-            then
-              aliases="$aliases latest"
-            fi
-          else
-            echo "::warning title=Documentation was not published::" \
-              "Don't know how to handle '$REF' to make 'mike' version."
-            exit 0
-          fi
-          echo "version=$version" >> $GITHUB_OUTPUT
-          echo "aliases=$aliases" >> $GITHUB_OUTPUT
-
       - name: Fetch sources
-        if: steps.mike-metadata.outputs.version
         uses: actions/checkout@v4
         with:
           submodules: true
 
       - name: Setup Git user and e-mail
-        if: steps.mike-metadata.outputs.version
         uses: frequenz-floss/setup-git-user@v2
 
       - name: Set up Python
-        if: steps.mike-metadata.outputs.version
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
           cache: 'pip'
 
       - name: Install build dependencies
-        if: steps.mike-metadata.outputs.version
         run: |
           python -m pip install -U pip
           python -m pip install .[dev-mkdocs]
           pip freeze
 
+      - name: Calculate and check version
+        id: mike-version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPO: ${{ github.repository }}
+          GIT_REF: ${{ github.ref }}
+          GIT_SHA: ${{ github.sha }}
+        run: |
+          python -m frequenz.repo.config.cli.version.mike.info
+
       - name: Fetch the gh-pages branch
-        if: steps.mike-metadata.outputs.version
+        if: steps.mike-version.outputs.version
         run: git fetch origin gh-pages --depth=1
 
-      - name: Publish site
-        if: steps.mike-metadata.outputs.version
+      - name: Build site
+        if: steps.mike-version.outputs.version
         env:
-          VERSION: ${{ steps.mike-metadata.outputs.version }}
-          ALIASES: ${{ steps.mike-metadata.outputs.aliases }}
+          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
+
+      - name: Sort site versions
+        if: steps.mike-version.outputs.version
+        run: |
+          git checkout gh-pages
+          python -m frequenz.repo.config.cli.version.mike.sort versions.json
+          git commit -a -m "Sort versions.json"
+
+      - name: Publish site
+        if: steps.mike-version.outputs.version
         run: |
-          mike deploy --push --update-aliases "$VERSION" $ALIASES
+          git push origin gh-pages
 
   create-github-release:
     name: Create GitHub release
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -157,11 +157,14 @@ These are the steps to create a new release:
 
 ##  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 containers 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
+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:
 
@@ -175,6 +178,6 @@ 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.
+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.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -7,6 +7,7 @@ exclude mkdocs.yml
 exclude noxfile.py
 exclude src/conftest.py
 recursive-exclude .github *
+recursive-exclude benchmarks *
 recursive-exclude docs *
 recursive-exclude tests *
 recursive-include py *.pyi
diff --git a/README.md b/README.md
@@ -10,10 +10,10 @@ A development kit to interact with the Frequenz development platform.
 
 ## Supported Platforms
 
-This SDK is supported on and thoroughly tested with the following platforms:
+The following platforms are officially supported (test):
 
 - **Python:** 3.11
-- **Operating System:** Ubuntu 20.04
+- **Operating System:** Ubuntu Linux 20.04
 - **Architectures:** amd64, arm64
 
 ## Quick Start
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -66,6 +66,15 @@ This version ships an experimental version of the **Power Manager**, adds prelim
 
 - Consumption and production power formulas have been removed.
 
+- The documentation was improved to:
+
+  * Show signatures with types.
+  * Show the inherited members.
+  * Documentation for pre-releases are now published.
+  * Show the full tag name as the documentation version.
+  * All development branches now have their documentation published (there is no `next` version anymore).
+  * Fix the order of the documentation versions.
+
 ## Bug Fixes
 
 - Fix rendering of diagrams in the documentation.
diff --git a/docs/_css/mkdocstrings.css b/docs/_css/mkdocstrings.css
diff --git a/docs/_css/style.css b/docs/_css/style.css
@@ -29,7 +29,7 @@ a.external:hover::after, a.md-nav__link[href^="https:"]:hover::after {
 
 /* Code annotations with numbers.
  *
- * Normally annothations are shown with a (+) button that expands the
+ * Normally annotations are shown with a (+) button that expands the
  * annotation. To be able to explain code step by step, it is good to have
  * annotations with numbers, to be able to follow the notes in a particular
  * order.
diff --git a/docs/_img/logo.png b/docs/_img/logo.png
diff --git a/docs/_overrides/main.html b/docs/_overrides/main.html
diff --git a/docs/_scripts/macros.py b/docs/_scripts/macros.py
@@ -35,6 +35,40 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
+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 hook the plugin into.
+    """
+    # get mkdocstrings' Python handler
+    python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
+
+    # get the `update_env` method of the Python handler
+    update_env = python_handler.update_env
+
+    # override the `update_env` method of the Python handler
+    def patched_update_env(markdown: md.Markdown, config: dict[str, Any]) -> None:
+        update_env(markdown, config)
+
+        # get the `convert_markdown` filter of the env
+        convert_markdown = python_handler.env.filters["convert_markdown"]
+
+        # build a chimera made of macros+mkdocstrings
+        def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
+            return convert_markdown(env.render(markdown), *args, **kwargs)
+
+        # patch the filter
+        python_handler.env.filters["convert_markdown"] = render_convert
+
+    # 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.
 
@@ -65,29 +99,5 @@ def glossary(term: str, text: str | None = None) -> str:
         link_path = os.path.relpath(glossary_path, current_path.parent)
         return f"[{text or term}]({link_path}#{_slugify(term)})"
 
-    # 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")
-
-    # get the `update_env` method of the Python handler
-    update_env = python_handler.update_env
-
-    # override the `update_env` method of the Python handler
-    def patched_update_env(markdown: md.Markdown, config: dict[str, Any]) -> None:
-        update_env(markdown, config)
-
-        # get the `convert_markdown` filter of the env
-        convert_markdown = python_handler.env.filters["convert_markdown"]
-
-        # build a chimera made of macros+mkdocstrings
-        def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
-            return convert_markdown(env.render(markdown), *args, **kwargs)
-
-        # patch the filter
-        python_handler.env.filters["convert_markdown"] = render_convert
-
-    # patch the method
-    python_handler.update_env = patched_update_env
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)
diff --git a/docs/_scripts/mkdocstrings_autoapi.py b/docs/_scripts/mkdocstrings_autoapi.py
@@ -3,6 +3,6 @@
 
 """Generate the code reference pages."""
 
-from frequenz.repo.config import mkdocs
+from frequenz.repo.config.mkdocs import api_pages
 
-mkdocs.generate_python_api_pages("src", "reference")
+api_pages.generate_python_api_pages("src", "reference")
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/noxfile.py b/noxfile.py
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/src/frequenz/sdk/conftest.py b/src/frequenz/sdk/conftest.py

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,6 @@`
`13`	`13`	`"python_package": "frequenz.sdk",`
`14`	`14`	`"pypi_package_name": "frequenz-sdk",`
`15`	`15`	`"github_repo_name": "frequenz-sdk-python",`
`16`		`- "default_codeowners": "@frequenz-floss/python-sdk-team",`
`17`		`- "_template": "gh:frequenz-floss/frequenz-repo-config-python"`
	`16`	`+ "default_codeowners": "@frequenz-floss/python-sdk-team"`
`18`	`17`	`}`
`19`	`18`	`}`