Run normal linting on noxfile.py

Also fix issues found while running the linting and some inconsistencies
between installed dependencies in the CI run and individual sessions
runs, which now runs a better type check in the docs script.

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

Author: llucax

docs/mkdocstrings_autoapi.py

@@ -34,7 +34,7 @@ def with_underscore_not_init(part: str) -> bool:
 
 # type ignore because mkdocs_gen_files uses a very weird module-level
 # __getattr__() which messes up the type system
-nav = mkdocs_gen_files.Nav()
+nav = mkdocs_gen_files.Nav()  # type: ignore
 
 for path in sorted(Path(SRC_PATH).rglob("*.py")):
     module_path = path.relative_to(SRC_PATH).with_suffix("")

noxfile.py

@@ -1,30 +1,43 @@
 # License: MIT
 # Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
+"""Project's noxfile.
+
+For more information please see nox documentation:
+https://nox.thea.codes/en/stable/
+"""
+
 from typing import List
-import nox
 
+import nox
 
 FMT_DEPS = ["black", "isort"]
-LINT_DEPS = ["mypy", "pylint"]
 DOCSTRING_DEPS = ["pydocstyle", "darglint"]
 PYTEST_DEPS = ["pytest", "pytest-cov", "pytest-mock", "pytest-asyncio", "time-machine"]
 
 
-def source_file_paths(session: nox.Session) -> List[str]:
+def _source_file_paths(session: nox.Session) -> List[str]:
     """Return the file paths to run the checks on.
 
-    If positional arguments are present, we use those as the file paths, and if
-    not, we use all source files."""
+    If positional arguments are present in the nox session, we use those as the
+    file paths, and if not, we use all source files.
+
+    Args:
+        session: the nox session.
+
+    Returns:
+        the file paths to run the checks on.
+    """
     if session.posargs:
         return session.posargs
     return [
-            "benchmarks",
-            "docs",
-            "examples",
-            "src",
-            "tests",
-            ]
+        "benchmarks",
+        "docs",
+        "examples",
+        "src",
+        "tests",
+        "noxfile.py",
+    ]
 
 
 # Run all checks except `ci_checks` by default.  When running locally with just
@@ -46,9 +59,13 @@ def ci_checks_max(session: nox.Session) -> None:
     This is faster than running the checks separately, so it is suitable for CI.
 
     This does NOT run pytest_min, so that needs to be run separately as well.
+
+    Args:
+        session: the nox session.
     """
-    session.install(".[docs]", *PYTEST_DEPS, *FMT_DEPS, *LINT_DEPS,
-            *DOCSTRING_DEPS)
+    session.install(
+        ".[docs]", "mypy", "pylint", "nox", *PYTEST_DEPS, *FMT_DEPS, *DOCSTRING_DEPS
+    )
 
     formatting(session, False)
     mypy(session, False)
@@ -59,22 +76,32 @@ def ci_checks_max(session: nox.Session) -> None:
 
 @nox.session
 def formatting(session: nox.Session, install_deps: bool = True) -> None:
-    """Check code formatting with black and isort."""
+    """Check code formatting with black and isort.
+
+    Args:
+        session: the nox session.
+        install_deps: True if dependencies should be installed.
+    """
     if install_deps:
         session.install(*FMT_DEPS)
 
-    paths = source_file_paths(session)
+    paths = _source_file_paths(session)
     session.run("black", "--check", *paths)
     session.run("isort", "--check", *paths)
 
 
 @nox.session
 def mypy(session: nox.Session, install_deps: bool = True) -> None:
-    """Check type hints with mypy."""
+    """Check type hints with mypy.
+
+    Args:
+        session: the nox session.
+        install_deps: True if dependencies should be installed.
+    """
     if install_deps:
         # install the package itself as editable, so that it is possible to do
         # fast local tests with `nox -R -e mypy`.
-        session.install("-e", ".", "mypy", *PYTEST_DEPS)
+        session.install("-e", ".[docs]", "mypy", "nox", *PYTEST_DEPS)
 
     mypy_cmd = [
         "mypy",
@@ -100,20 +127,25 @@ def mypy(session: nox.Session, install_deps: bool = True) -> None:
     # checks for frequenz.sdk from the installed package instead of the src
     # directory.
     mypy_paths = [
-        path for path in source_file_paths(session) if not path.startswith("src")
+        path for path in _source_file_paths(session) if not path.startswith("src")
     ]
     session.run(*mypy_cmd, *mypy_paths)
 
 
 @nox.session
 def pylint(session: nox.Session, install_deps: bool = True) -> None:
-    """Check for code smells with pylint."""
+    """Check for code smells with pylint.
+
+    Args:
+        session: the nox session.
+        install_deps: True if dependencies should be installed.
+    """
     if install_deps:
         # install the package itself as editable, so that it is possible to do
         # fast local tests with `nox -R -e pylint`.
-        session.install("-e", ".[docs]", "pylint", *PYTEST_DEPS)
+        session.install("-e", ".[docs]", "pylint", "nox", *PYTEST_DEPS)
 
-    paths = source_file_paths(session)
+    paths = _source_file_paths(session)
     session.run(
         "pylint",
         "--extension-pkg-whitelist=pydantic",
@@ -123,11 +155,16 @@ def pylint(session: nox.Session, install_deps: bool = True) -> None:
 
 @nox.session
 def docstrings(session: nox.Session, install_deps: bool = True) -> None:
-    """Check docstring tone with pydocstyle and param descriptions with darglint."""
+    """Check docstring tone with pydocstyle and param descriptions with darglint.
+
+    Args:
+        session: the nox session.
+        install_deps: True if dependencies should be installed.
+    """
     if install_deps:
         session.install(*DOCSTRING_DEPS, "toml")
 
-    paths = source_file_paths(session)
+    paths = _source_file_paths(session)
     session.run("pydocstyle", *paths)
 
     # Darglint checks that function argument and return values are documented.
@@ -136,7 +173,7 @@ def docstrings(session: nox.Session, install_deps: bool = True) -> None:
     # which case we use those untouched.
     darglint_paths = session.posargs or filter(
         lambda path: not (path.startswith("tests") or path.startswith("benchmarks")),
-        source_file_paths(session),
+        _source_file_paths(session),
     )
     session.run(
         "darglint",
@@ -147,29 +184,37 @@ def docstrings(session: nox.Session, install_deps: bool = True) -> None:
 
 @nox.session
 def pytest_max(session: nox.Session, install_deps: bool = True) -> None:
-    """Test the code against max dependency versions with pytest."""
+    """Test the code against max dependency versions with pytest.
+
+    Args:
+        session: the nox session.
+        install_deps: True if dependencies should be installed.
+    """
     if install_deps:
         # install the package itself as editable, so that it is possible to do
         # fast local tests with `nox -R -e pytest_max`.
         session.install("-e", ".", *PYTEST_DEPS)
 
-    _pytest_impl(session, "max", install_deps)
+    _pytest_impl(session, "max")
 
 
 @nox.session
 def pytest_min(session: nox.Session, install_deps: bool = True) -> None:
-    """Test the code against min dependency versions with pytest."""
+    """Test the code against min dependency versions with pytest.
+
+    Args:
+        session: the nox session.
+        install_deps: True if dependencies should be installed.
+    """
     if install_deps:
         # install the package itself as editable, so that it is possible to do
         # fast local tests with `nox -R -e pytest_min`.
         session.install("-e", ".", *PYTEST_DEPS, "-r", "minimum-requirements-ci.txt")
 
-    _pytest_impl(session, "min", install_deps)
+    _pytest_impl(session, "min")
 
 
-def _pytest_impl(
-    session: nox.Session, max_or_min_deps: str, install_deps: bool
-) -> None:
+def _pytest_impl(session: nox.Session, max_or_min_deps: str) -> None:
     session.run(
         "pytest",
         "-W=all",