pre-commit-config.yaml.template

# Pre-commit hooks for scientific Python repos (copy to .pre-commit-config.yaml).
# Install once per clone:  pip install pre-commit && pre-commit install
# Docstring style is Google everywhere: pydoclint --style google, darglint2 -s google.
# ruff runs NO docstring checks by default - enable them in pyproject.toml:
#   [tool.ruff.lint]
#   extend-select = ["D"]        # D1xx flag MISSING docstrings
#   [tool.ruff.lint.pydocstyle]
#   convention = "google"
# (pydoclint/darglint2 only validate docstrings that exist; without the D rules
# an undocumented module passes the stack green. Exempt tests/ or legacy dirs
# via [tool.ruff.lint.per-file-ignores].)
repos:
  # Format Python code consistently (black-jupyter also formats .ipynb cells;
  # the plain 'black' id skips notebooks).
  - repo: https://github.com/psf/black
    rev: 25.9.0
    hooks:
      - id: black-jupyter

  # Strip notebook outputs before commit: keeps diffs reviewable and keeps
  # data, rendered plots, and tokens out of git history.
  - repo: https://github.com/kynan/nbstripout
    rev: 0.8.1
    hooks:
      - id: nbstripout

  # Lint and auto-fix (docstring checks only with the D rules enabled, above).
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.1
    hooks:
      - id: ruff
        args: [--fix]

  # Docstring signature/section validation.
  - repo: local
    hooks:
      - id: pydoclint
        name: pydoclint
        entry: pydoclint
        args: [--style, google]
        language: python
        types: [python]
        additional_dependencies: ["pydoclint"]
        # Add legacy files that predate the hooks to this regex instead of fixing
        # them wholesale; new files must pass.
        # exclude: "^legacy_module\\.py$"
      - id: darglint2
        name: darglint2
        entry: darglint2
        language: python
        types: [python]
        args: [-s, google, -z, full]
        additional_dependencies: ["darglint2"]
        # exclude: "^legacy_module\\.py$"