Prepare v0.4.0 release (frequenz-floss#96)

- Bump repo-config version in templates and docs
- Prepare release notes for the new release
- Add missing extension to the cookiecutter replay file
- Update files by regenerating the cookiecutter template

Author: llucax

.cookiecutter-replay.json

@@ -15,6 +15,7 @@
     "default_codeowners": "@frequenz-floss/python-sdk-team",
     "_extensions": [
       "jinja2_time.TimeExtension",
+      "local_extensions.as_identifier",
       "local_extensions.default_codeowners",
       "local_extensions.github_repo_name",
       "local_extensions.keywords",

.github/RELEASE_NOTES.template.md

@@ -6,7 +6,7 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with --> 
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 

RELEASE_NOTES.md

@@ -2,24 +2,51 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release only ships fixes and improvements for Cookiecutter templates, it is recommended for existing projects to regenerate the templates.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with --> 
+### Cookiecutter templates
+
+* You might want to remove the `_output_dir` from the
+  `.cookiecutter-replay.json` file, if there is one in your project.
+* You will need to manually add `local_extensions.as_identifier` to the `_extensions` key in the `.cookiecutter-replay.json` file before running the replay.
 
 ## New Features
 
 ### Cookiecutter templates
 
 * Add linting to the CI with `protolint` for API projects.
-* Bump SDK version to v0.22.0.
 * Capitalize project name in title and expand shortened words.
-* Add a few more default keywords.
-* Add variable reference documentation.
+* Add templates variables reference documentation in the genrated docs and when running Cookiecutter.
+* Do some basic templates variables validation.
+
+* `labeler` workflow configuration
+
+  * Label `docs/*.py` as tooling.
+  * Add example on how to exclude files.
+
+* `pyproject.toml`
+
+  * Bump SDK version to v0.22.0.
+  * Disable `pylint`'s `unsubscriptable-object` check.
+  * Add a few more default keywords.
+  * Run `isort` in `benchmarks/` too
+
+* `mkdocs`
+
+  * Add more cross-reference inventories: `typing-extensions`, `frequenz-sdk`, `frequenz-channels`, `grpc`.
+  * Add some extra markdown plugins: code annotations, copy button and line numbers, keys representation.
+  * Be strict when building the docs (any warning will make the generation fail).
 
 ## Bug Fixes
 
-### Cookiecutter
+### Cookiecutter templates
 
 * Fix hardcoded MIT license headers. Now the user selected license is used instead.
+* Properly handle project names with `-` and `_` in them.
+
+* `pyproject.toml`
+
+  * Add missing `repo-config` to `dev-mkdocs` dependencies.
+  * Fix wrong optional dependency name for `dev` dependencies.

cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml

@@ -5,7 +5,7 @@
 requires = [
   "setuptools == 67.7.2",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[{{cookiecutter.type}}] == 0.3.0",
+  "frequenz-repo-config[{{cookiecutter.type}}] == 0.4.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -70,7 +70,7 @@ dev-mkdocs = [
   "mkdocs-material == 9.1.16",
   "mkdocs-section-index == 0.3.5",
   "mkdocstrings[python] == 0.22.0",
-  "frequenz-repo-config[{{cookiecutter.type}}] == 0.3.0",
+  "frequenz-repo-config[{{cookiecutter.type}}] == 0.4.0",
 ]
 dev-mypy = [
   "mypy == 1.2.0",
@@ -79,7 +79,7 @@ dev-mypy = [
 ]
 dev-noxfile = [
   "nox == 2023.4.22",
-  "frequenz-repo-config[{{cookiecutter.type}}] == 0.3.0",
+  "frequenz-repo-config[{{cookiecutter.type}}] == 0.4.0",
 ]
 dev-pylint = [
   "pylint == 2.17.3",

mkdocs.yml

@@ -22,6 +22,8 @@ theme:
     repo: fontawesome/brands/github
   custom_dir: docs/overrides
   features:
+    - content.code.annotate
+    - content.code.copy
     - navigation.instant
     - navigation.tabs
     - navigation.top
@@ -62,16 +64,20 @@ markdown_extensions:
   - admonition
   - attr_list
   - pymdownx.details
-  - pymdownx.superfences
-  - pymdownx.tasklist
-  - pymdownx.tabbed
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.keys
   - pymdownx.snippets:
       check_paths: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
           class: mermaid
           format: "!!python/name:pymdownx.superfences.fence_code_format"
+  - pymdownx.tabbed
+  - pymdownx.tasklist
   - toc:
       permalink: "¤"
 
@@ -103,6 +109,7 @@ plugins:
             - https://nox.thea.codes/en/stable/objects.inv
             - https://setuptools.pypa.io/en/latest/objects.inv
             - https://oprypin.github.io/mkdocs-gen-files/objects.inv
+            - https://typing-extensions.readthedocs.io/en/stable/objects.inv
   - search
   - section-index
 

pyproject.toml

@@ -87,7 +87,7 @@ dev-pytest = [
   "cookiecutter == 2.1.1", # For checking the cookiecutter scripts
 ]
 dev = [
-  "frequenz-repo-config[dev-mkdocs,dev-docstrings,dev-formatting,dev-gen-docs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+  "frequenz-repo-config[dev-mkdocs,dev-docstrings,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
 
 [project.urls]
@@ -104,7 +104,7 @@ include = '\.pyi?$'
 [tool.isort]
 profile = "black"
 line_length = 88
-src_paths = ["src", "examples", "tests"]
+src_paths = ["benchmarks", "examples", "src", "tests"]
 
 [tool.pylint.similarities]
 ignore-comments = ['yes']

src/frequenz/repo/config/__init__.py

@@ -286,7 +286,7 @@
 requires = [
   "setuptools >= 67.3.2, < 68",
   "setuptools_scm[toml] >= 7.1.0, < 8",
-  "frequenz-repo-config[api] >= 0.1.0, < 0.3.0",
+  "frequenz-repo-config[api] >= 0.3.0, < 0.4.0",
 ]
 build-backend = "setuptools.build_meta"
 

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml

@@ -5,7 +5,7 @@
 requires = [
   "setuptools == 67.7.2",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[actor] == 0.3.0",
+  "frequenz-repo-config[actor] == 0.4.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -52,7 +52,7 @@ dev-mkdocs = [
   "mkdocs-material == 9.1.16",
   "mkdocs-section-index == 0.3.5",
   "mkdocstrings[python] == 0.22.0",
-  "frequenz-repo-config[actor] == 0.3.0",
+  "frequenz-repo-config[actor] == 0.4.0",
 ]
 dev-mypy = [
   "mypy == 1.2.0",
@@ -61,7 +61,7 @@ dev-mypy = [
 ]
 dev-noxfile = [
   "nox == 2023.4.22",
-  "frequenz-repo-config[actor] == 0.3.0",
+  "frequenz-repo-config[actor] == 0.4.0",
 ]
 dev-pylint = [
   "pylint == 2.17.3",

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml

@@ -5,7 +5,7 @@
 requires = [
   "setuptools == 67.7.2",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[api] == 0.3.0",
+  "frequenz-repo-config[api] == 0.4.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -50,7 +50,7 @@ dev-mkdocs = [
   "mkdocs-material == 9.1.16",
   "mkdocs-section-index == 0.3.5",
   "mkdocstrings[python] == 0.22.0",
-  "frequenz-repo-config[api] == 0.3.0",
+  "frequenz-repo-config[api] == 0.4.0",
 ]
 dev-mypy = [
   "mypy == 1.2.0",
@@ -59,7 +59,7 @@ dev-mypy = [
 ]
 dev-noxfile = [
   "nox == 2023.4.22",
-  "frequenz-repo-config[api] == 0.3.0",
+  "frequenz-repo-config[api] == 0.4.0",
 ]
 dev-pylint = [
   "pylint == 2.17.3",

tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml

@@ -5,7 +5,7 @@
 requires = [
   "setuptools == 67.7.2",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[app] == 0.3.0",
+  "frequenz-repo-config[app] == 0.4.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -51,7 +51,7 @@ dev-mkdocs = [
   "mkdocs-material == 9.1.16",
   "mkdocs-section-index == 0.3.5",
   "mkdocstrings[python] == 0.22.0",
-  "frequenz-repo-config[app] == 0.3.0",
+  "frequenz-repo-config[app] == 0.4.0",
 ]
 dev-mypy = [
   "mypy == 1.2.0",
@@ -60,7 +60,7 @@ dev-mypy = [
 ]
 dev-noxfile = [
   "nox == 2023.4.22",
-  "frequenz-repo-config[app] == 0.3.0",
+  "frequenz-repo-config[app] == 0.4.0",
 ]
 dev-pylint = [
   "pylint == 2.17.3",