feat(interrogate): add docstring coverage checks to prek and lint

.pre-commit-config.yaml

@@ -34,6 +34,13 @@ repos:
       pass_filenames: false
       language: system  # use the project's own pyrefly install so versions stay in sync with pyproject.toml
 
+# interrogate (docstring coverage)
+- repo: https://github.com/econchick/interrogate
+  rev: 1.7.0
+  hooks:
+    - id: interrogate
+      pass_filenames: false  # config (incl. exclude paths) lives in pyproject.toml
+
 # sqlfluff
 - repo: https://github.com/sqlfluff/sqlfluff
   rev: 3.5.0

Makefile

@@ -39,14 +39,17 @@ lock:
 format:
 	uv run ruff format --check .
 
-lint: lint-python lint-sql
+lint: lint-python lint-sql lint-docstrings
 
 lint-python:
 	uv run ruff check --output-format=github .
 
 lint-sql:
 	uv run sqlfluff lint .
 
+lint-docstrings:
+	uv run interrogate
+
 type:
 	uv run pyrefly check
 

README.md

@@ -99,6 +99,7 @@ The checks contained in this repo include (in the order in which they run):
 * `ruff` checks code for "lint"
 * `pyrefly` is used for static type checking
 * `sqlfluff` checks and fixes sql formatting and linting
+* `interrogate` checks docstring coverage
 * `uv` checks on valid and aligned pyproject.toml and uv.lock files
 * `commitlint` enforces commit message conforms to [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format
 
@@ -114,4 +115,3 @@ If you absolutely must commit without adhering to the prek hooks, then you can u
 * [ ] switch from `nox` to `tox` (tox is more widely used and prevents python abuse - e.g. setup.py can become too complicated)
   * make sure tox goes fast - https://hynek.me/articles/turbo-charge-tox/
 * [ ] switch `coverage` to not report until the end and combine all coverage reports together into one
-* [ ] add [`interrogate`](https://github.com/econchick/interrogate) to prek and test suite

pyproject.toml

@@ -23,6 +23,7 @@ df = [
 
 [dependency-groups]
 dev = [
+    "interrogate >=1.7.0,<2",
     "mkdocs >=1.6.0,<2",
     "mkdocs-material >=9.4.5,<10",
     "mkdocstrings[python] >=0.25.2,<1",
@@ -41,6 +42,16 @@ dev = [
 packages = ["src/sample"]
 
 
+#############
+# Interrogate
+#############
+[tool.interrogate]
+fail-under = 100
+ignore-init-method = true
+verbose = 1
+exclude = ["tests", "docs", "noxfile.py"]
+
+
 ##########
 # Coverage
 ##########

src/sample/sample_with_extra_install.py

@@ -1,3 +1,7 @@
+"""
+A placeholder module for sample content requiring the "df" extra install
+"""
+
 try:
     import pandas as pd
 except ImportError:
@@ -7,6 +11,16 @@
 
 
 class SampleWithExtraInstall(Sample):
+    """
+    Sample class requiring the "df" extra install
+    """
+
     def sample_extra(self):
+        """
+        Sample method which returns an empty pandas DataFrame
+
+        Returns:
+            df (pandas.DataFrame): empty DataFrame
+        """
         df = pd.DataFrame()
         return df