Add linting of code examples in docstrings (frequenz-floss#115)

Also prepare for the v0.5.0 release.

- Update repo-config version
- Add support for linting code examples in docstrings
- Add support for the `part:pytest` label
- mkdocs: Ignore the top-level `conftest` module
- Lint docstrings examples
- Skip examples linting for `__init__.py` files
- cookiecutter: Add a `pytest` hook to lint docstring examples
- Add summary to release notes

Fixes frequenz-floss#27.

Author: llucax

.github/ISSUE_TEMPLATE/bug.yml

@@ -61,6 +61,7 @@ body:
         - Tools to configure nox (part:nox)
         - Tools to configure protobufs (part:protobuf)
         - Tools to configure the CI (part:ci)
+        - Tools to configure pytest (part:pytest)
     validations:
       required: true
   - type: textarea

.github/keylabeler.yml

@@ -27,3 +27,4 @@ labelMappings:
   "part:model-only": "part:model-only"
   "part:nox": "part:nox"
   "part:protobuf": "part:protobuf"
+  "part:pytest": "part:pytest"

.github/labeler.yml

@@ -69,3 +69,9 @@
       - "src/frequenz/repo/config/protobuf*"
     all:
       - "!tests*/**"
+
+"part:pytest":
+  - any:
+      - "src/frequenz/repo/config/pytest"
+    all:
+      - "!tests*/**"

MANIFEST.in

@@ -6,6 +6,7 @@ exclude CODEOWNERS
 exclude CONTRIBUTING.md
 exclude mkdocs.yml
 exclude noxfile.py
+exclude src/conftest.py
 recursive-exclude .github *
 recursive-exclude cookiecutter *
 recursive-exclude docs *

README.md

@@ -42,7 +42,7 @@ directory will be created with the generated project name. For example:
 cd ~/devel
 cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
     --directory=cookiecutter \
-    --checkout v0.4.0
+    --checkout v0.5.0
 ```
 
 This command will prompt you for the project type, name, and other

RELEASE_NOTES.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release adds linting of code examples in *docstrings*, a workflow to check if PRs have updated the release notes and an [editorconfig](https://editorconfig.org/) file, as well as a bunch of bug fixes.
 
 ## Upgrading
 
@@ -38,6 +38,12 @@
 
 ## New Features
 
+- Add support for linting code examples found in *docstrings*.
+
+  A new module `frequenz.repo.config.pytest.examples` is added with an utility function to be able to easily collect and lint code examples in *docstrings*.
+
+  There is also a new optional dependency `extra-lint-examples` to easily pull the dependencies needed to do this linting. Please have a look at the documentation in the `frequenz.repo.config` package for more details.
+
 ### Cookiecutter template
 
 - Add a new GitHub workflow to check that release notes were updated.
@@ -52,6 +58,14 @@
 
 - Add an `.editorconfig` file to ensure a common basic editor configuration for different file types.
 
+- Add a `pytest` hook to collect and lint code examples found in *docstrings* using `pylint`.
+
+  Examples found in code *docstrings* in the `src/` directory will now be collected and checked using `pylint`. This is done via the file `src/conftest.py`, which hooks into `pytest`, so to only check the examples you can run `pylint src`.
+
+  !!! info
+
+      There is a bug in the library used to extract the examples that prevents from collecting examples from `__init__.py` files. See https://github.com/frequenz-floss/frequenz-repo-config-python/issues/113 for more details.
+
 ## Bug Fixes
 
 - The distribution package doesn't include tests and other useless files anymore.

cookiecutter/{{cookiecutter.github_repo_name}}/MANIFEST.in

@@ -9,6 +9,7 @@ exclude CODEOWNERS
 exclude CONTRIBUTING.md
 exclude mkdocs.yml
 exclude noxfile.py
+exclude src/conftest.py
 recursive-exclude .github *
 recursive-exclude docs *
 {%- if cookiecutter.type == "api" %}

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.4.0",
+  "frequenz-repo-config[{{cookiecutter.type}}] == 0.5.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.4.0",
+  "frequenz-repo-config[{{cookiecutter.type}}] == 0.5.0",
 ]
 dev-mypy = [
   "mypy == 1.2.0",
@@ -79,23 +79,22 @@ dev-mypy = [
 ]
 dev-noxfile = [
   "nox == 2023.4.22",
-  "frequenz-repo-config[{{cookiecutter.type}}] == 0.4.0",
+  "frequenz-repo-config[{{cookiecutter.type}}] == 0.5.0",
 ]
 dev-pylint = [
   "pylint == 2.17.3",
   # For checking the noxfile, docs/ script, and tests
   "{{cookiecutter.pypi_package_name}}[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
-{%- if cookiecutter.type == "api" %}
-dev-pytest = ["pytest == 7.3.1"]
-{%- else %}
 dev-pytest = [
   "pytest == 7.3.1",
+  "frequenz-repo-config[extra-lint-examples] == 0.5.0",
+{%- if cookiecutter.type != "api" %}
   "pytest-mock == 3.10.0",
   "pytest-asyncio == 0.21.0",
   "async-solipsism == 0.5",
-]
 {%- endif %}
+]
 dev = [
   "{{cookiecutter.pypi_package_name}}[dev-mkdocs,dev-docstrings,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
@@ -138,7 +137,7 @@ disable = [
 
 [tool.pytest.ini_options]
 {%- if cookiecutter.type != "api" %}
-testpaths = ["tests"]
+testpaths = ["tests", "src"]
 asyncio_mode = "auto"
 required_plugins = ["pytest-asyncio", "pytest-mock"]
 {%- else %}
@@ -147,7 +146,7 @@ testpaths = ["pytests"]
 {%- if cookiecutter.type != "api" %}
 
 [[tool.mypy.overrides]]
-module = ["async_solipsism", "async_solipsism.*"]
+module = ["async_solipsism", "async_solipsism.*", "sybil", "sybil.*"]
 ignore_missing_imports = true
 {%- endif %}
 {%- if cookiecutter.type == "api" %}

cookiecutter/{{cookiecutter.github_repo_name}}/src/conftest.py

@@ -0,0 +1,13 @@
+# License: {{cookiecutter.license}}
+# Copyright © {% now 'utc', '%Y' %} {{cookiecutter.author_name}}
+
+"""Validate docstring code examples.
+
+Code examples are often wrapped in triple backticks (```) within docstrings.
+This plugin extracts these code examples and validates them using pylint.
+"""
+
+from frequenz.repo.config.pytest import examples
+from sybil import Sybil
+
+pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()

docs/index.md

@@ -35,7 +35,7 @@ Then simply run [Cookiecutter] where you want to create the new project:
 
 ```sh
 cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
-    --directory=cookiecutter --checkout v0.4.0
+    --directory=cookiecutter --checkout v0.5.0
 ```
 
 This command will prompt you for the project type, name, and other