refactor: Write comments, not docstrings in internal modules/scripts

Author: pawamoy

project/config/ruff.toml.jinja

@@ -47,17 +47,24 @@ ignore = [
 ]
 
 [lint.per-file-ignores]
-"src/*/cli.py" = [
+"src/**/cli.py" = [
     "T201",  # Print statement
 ]
 "src/*/debug.py" = [
     "T201",  # Print statement
 ]
+"!src/*/*.py" = [
+    "D100",  # Missing docstring in public module
+]
+"!src/**.py" = [
+    "D101",  # Missing docstring in public class
+    "D103",  # Missing docstring in public function
+]
 "scripts/*.py" = [
     "INP001",  # File is part of an implicit namespace package
     "T201",  # Print statement
 ]
-"tests/*.py" = [
+"tests/**.py" = [
     "ARG005",  # Unused lambda argument
     "FBT001",  # Boolean positional arg in function definition
     "PLR2004",  # Magic value used in comparison

project/duties.py.jinja

@@ -26,15 +26,15 @@ PTY = not WINDOWS and not CI
 MULTIRUN = os.environ.get("MULTIRUN", "0") == "1"
 
 
-def pyprefix(title: str) -> str:  # noqa: D103
+def pyprefix(title: str) -> str:
     if MULTIRUN:
         prefix = f"(python{sys.version_info.major}.{sys.version_info.minor})"
         return f"{prefix:14}{title}"
     return title
 
 
 @contextmanager
-def material_insiders() -> Iterator[bool]:  # noqa: D103
+def material_insiders() -> Iterator[bool]:
     if "+insiders" in pkgversion("mkdocs-material"):
         os.environ["MATERIAL_INSIDERS"] = "true"
         try:

project/scripts/gen_api_ref.py.jinja

@@ -1,4 +1,4 @@
-"""Generate the code reference pages and navigation."""
+# Generate the API reference pages and navigation.
 
 from pathlib import Path
 

project/scripts/gen_credits.py.jinja

@@ -1,4 +1,4 @@
-"""Script to generate the project's credits."""
+# Script to generate the project's credits.
 
 from __future__ import annotations
 

project/scripts/get_version.py.jinja

@@ -1,4 +1,4 @@
-"""Get current project version from Git tags or changelog."""
+# Get current project version from Git tags or changelog.
 
 import re
 from contextlib import suppress
@@ -13,7 +13,6 @@ _default_scm_version = SCMVersion(Version("0.0.0"), None, False, None, None)  #
 
 
 def get_version() -> str:
-    """Get current project version from Git tags or changelog."""
     scm_version = get_version_from_scm(_root) or _default_scm_version
     if scm_version.version <= Version("0.1"):  # Missing Git tags?
         with suppress(OSError, StopIteration):  # noqa: SIM117

project/scripts/make.py.jinja

@@ -1,6 +1,4 @@
 #!/usr/bin/env python3
-"""Management commands."""
-
 from __future__ import annotations
 
 import os

project/scripts/{% if insiders %}insiders.py{% endif %}.jinja

@@ -1,4 +1,4 @@
-"""Functions related to Insiders funding goals."""
+# Functions related to Insiders funding goals.
 
 from __future__ import annotations
 
@@ -23,7 +23,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(f"mkdocs.logs.{__name__}")
 
 
-def human_readable_amount(amount: int) -> str:  # noqa: D103
+def human_readable_amount(amount: int) -> str:
     str_amount = str(amount)
     if len(str_amount) >= 4:  # noqa: PLR2004
         return f"{str_amount[: len(str_amount) - 3]},{str_amount[-3:]}"
@@ -32,16 +32,12 @@ def human_readable_amount(amount: int) -> str:  # noqa: D103
 
 @dataclass
 class Project:
-    """Class representing an Insiders project."""
-
     name: str
     url: str
 
 
 @dataclass
 class Feature:
-    """Class representing an Insiders feature."""
-
     name: str
     ref: str | None
     since: date | None
@@ -68,8 +64,6 @@ class Feature:
 
 @dataclass
 class Goal:
-    """Class representing an Insiders goal."""
-
     name: str
     amount: int
     features: list[Feature]
@@ -96,16 +90,6 @@ class Goal:
 
 
 def load_goals(data: str, funding: int = 0, project: Project | None = None) -> dict[int, Goal]:
-    """Load goals from JSON data.
-
-    Parameters:
-        data: The JSON data.
-        funding: The current total funding, per month.
-        origin: The origin of the data (URL).
-
-    Returns:
-        A dictionaries of goals, keys being their target monthly amount.
-    """
     goals_data = yaml.safe_load(data)["goals"]
     return {
         amount: Goal(
@@ -153,15 +137,6 @@ def _load_goals(source: str | tuple[str, str, str], funding: int = 0) -> dict[in
 
 
 def funding_goals(source: str | list[str | tuple[str, str, str]], funding: int = 0) -> dict[int, Goal]:
-    """Load funding goals from a given data source.
-
-    Parameters:
-        source: The data source (local file path or URL).
-        funding: The current total funding, per month.
-
-    Returns:
-        A dictionaries of goals, keys being their target monthly amount.
-    """
     if isinstance(source, str):
         return _load_goals_from_disk(source, funding)
     goals = {}
@@ -176,18 +151,10 @@ def funding_goals(source: str | list[str | tuple[str, str, str]], funding: int =
 
 
 def feature_list(goals: Iterable[Goal]) -> list[Feature]:
-    """Extract feature list from funding goals.
-
-    Parameters:
-        goals: A list of funding goals.
-
-    Returns:
-        A list of features.
-    """
     return list(chain.from_iterable(goal.features for goal in goals))
 
 
-def load_json(url: str) -> str | list | dict:  # noqa: D103
+def load_json(url: str) -> str | list | dict:
     with urlopen(url) as response:  # noqa: S310
         return json.loads(response.read().decode())