cookiecutter: Add a pytest hook to lint docstring examples

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`.

We also need to update the regex to use the current development version
of the package in the tests because now we also use the
`extra-lint-examples` optional dependency.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

RELEASE_NOTES.md

@@ -58,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

@@ -86,16 +86,15 @@ dev-pylint = [
   # 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()

tests/integration/test_cookiecutter_generation.py

@@ -283,12 +283,8 @@ def _update_pyproject_repo_config_dep(
         repo_type: Type of the repo to generate.
         repo_path: Path to the generated repo.
     """
-    repo_config_dep = (
-        f"frequenz-repo-config[{repo_type.value}] @ file://{repo_config_path}"
-    )
-    repo_config_dep_re = re.compile(
-        rf"""frequenz-repo-config\[{repo_type.value}\][^"]+"""
-    )
+    repo_config_dep = rf"frequenz-repo-config[\1] @ file://{repo_config_path}"
+    repo_config_dep_re = re.compile(r"""frequenz-repo-config\[([^]]+)\][^"]+""")
 
     with open(repo_path / "pyproject.toml", encoding="utf8") as pyproject_file:
         pyproject_content = pyproject_file.read()

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/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 docs *
 recursive-exclude tests *

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

@@ -70,6 +70,7 @@ dev-pylint = [
 ]
 dev-pytest = [
   "pytest == 7.3.1",
+  "frequenz-repo-config[extra-lint-examples] == 0.5.0",
   "pytest-mock == 3.10.0",
   "pytest-asyncio == 0.21.0",
   "async-solipsism == 0.5",
@@ -112,12 +113,12 @@ disable = [
 ]
 
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+testpaths = ["tests", "src"]
 asyncio_mode = "auto"
 required_plugins = ["pytest-asyncio", "pytest-mock"]
 
 [[tool.mypy.overrides]]
-module = ["async_solipsism", "async_solipsism.*"]
+module = ["async_solipsism", "async_solipsism.*", "sybil", "sybil.*"]
 ignore_missing_imports = true
 
 [tool.setuptools_scm]

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/src/conftest.py

@@ -0,0 +1,13 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""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()

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/MANIFEST.in

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

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/py/conftest.py

@@ -0,0 +1,13 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""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()