Allow pydocstyle ruff rules without enabling them

This updates the produced files to be compatible with pydocstyle rules and gives instructions on how to turn on checking

Author: coretl

.github/pages/make_switcher.py

@@ -1,3 +1,5 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
 import json
 import logging
 from argparse import ArgumentParser
@@ -6,6 +8,7 @@
 
 
 def report_output(stdout: bytes, label: str) -> list[str]:
+    """Print and return something received frm stdout."""
     ret = stdout.decode().strip().split("\n")
     print(f"{label}: {ret}")
     return ret
@@ -52,21 +55,20 @@ def get_versions(ref: str, add: str | None) -> list[str]:
     return versions
 
 
-def write_json(path: Path, repository: str, versions: str):
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
     org, repo_name = repository.split("/")
-    pages_url = f"https://{org}.github.io"
-    if repo_name != f"{org}.github.io":
-        # Only add the repo name if it isn't the source for the org pages site
-        pages_url += f"/{repo_name}"
     struct = [
-        {"version": version, "url": f"{pages_url}/{version}/"} for version in versions
+        {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+        for version in versions
     ]
     text = json.dumps(struct, indent=2)
     print(f"JSON switcher:\n{text}")
     path.write_text(text, encoding="utf-8")
 
 
 def main(args=None):
+    """Parse args and write switcher."""
     parser = ArgumentParser(
         description="Make a versions.json file from gh-pages directories"
     )

docs/how-to/check-docs-style.md

@@ -0,0 +1,42 @@
+# Check docs for style
+
+Ruff has the ability to check that you have:
+
+- Documented all public modules, classes, methods and functions
+- Written your docstrings according to a particular style
+- Not missed parameters from method and function docstrings
+
+This is not turned on by default, as it is not able to [distinguish between a missing docstring, and one that is inherited from a parent class](https://github.com/astral-sh/ruff/issues/9149)
+
+## Enabling docstring checking
+
+There are a number of competing docstring styles, ruff supports numpy, google and pep257. If you would like to check for the google docstring style, you can configure in ``pyproject.toml`` by:
+
+- Turning on the checker
+
+```toml
+[tool.ruff.lint]
+extend-select = [
+    # ...
+    "D",   # pydocstyle - https://docs.astral.sh/ruff/rules/#pydocstyle-d
+    # ...
+]
+```
+
+- Selecting a convention
+
+```toml
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+```
+
+- Ignoring docstring checking in tests
+
+```toml
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = [
+    # ...
+    "D",      # Don't check docstrings in tests
+    # ...
+]
+```

template/src/{{ package_name }}/__main__.py.jinja

@@ -1,3 +1,4 @@
+"""Interface for ``python -m {{package_name}}``."""
 from argparse import ArgumentParser
 from collections.abc import Sequence
 
@@ -7,6 +8,7 @@ __all__ = ["main"]
 
 
 def main(args: Sequence[str] | None = None) -> None:
+    """Argument parser for the CLI."""
     parser = ArgumentParser()
     parser.add_argument(
         "-v",
@@ -17,6 +19,5 @@ def main(args: Sequence[str] | None = None) -> None:
     parser.parse_args(args)
 
 
-# test with: python -m {{package_name}}
 if __name__ == "__main__":
     main()

template/{% if sphinx %}docs{% endif %}/conf.py.jinja

@@ -1,8 +1,9 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
 
 import sys
 from pathlib import Path

tests/test_example.py

@@ -165,6 +165,25 @@ def test_works_in_pyright_strict_mode(tmp_path: Path):
     run(f"./venv/bin/pyright {tmp_path}")
 
 
+def test_works_with_pydocstyle(tmp_path: Path):
+    copy_project(tmp_path)
+    pyproject_toml = tmp_path / "pyproject.toml"
+    text = (
+        pyproject_toml.read_text()
+        .replace('"C4",', '"C4", "D",')  # Enable all pydocstyle
+        .replace(
+            '"tests/**/*" = ["SLF001"]',
+            # But exclude on tests and allow o put their own docstring on __init__.py
+            '"tests/**/*" = ["SLF001", "D"]\n"__init__.py" = ["D104"]',
+        )
+    )
+    pyproject_toml.write_text(text)
+
+    # Ensure ruff is still happy
+    run = make_venv(tmp_path)
+    run("ruff check")
+
+
 def test_catalog_info(tmp_path: Path):
     copy_project(tmp_path)
     catalog_info_path = tmp_path / "catalog-info.yaml"