DIRACGrid / DIRACGrid/diracx

Add missing docstrings and guard against reST regressions (follow-up to #927)

Open
#1,004 0 comments 0 reactions 1 assignee Claimed by @martynia View on GitHub
enhancement
Dominant language
Python
Stars
19
Forks
45
Avg merge
4d 23h
Merged PRs (30d)
12

Description

### User Story

As a DiracX developer or extension author,
I want the public modules, classes, and functions to carry Google-style docstrings, with CI rejecting missing docstrings and legacy reST tags,
So that the mkdocstrings-generated API reference is complete and the convention adopted in #927 cannot silently regress.

### Feature Description

#927 harmonized the existing docstrings to Google style (PR #993) and enabled `[tool.ruff.lint.pydocstyle] convention = "google"`. This follow-up covers what was intentionally left out of that issue's scope:

1. Write the missing docstrings. The missing-docstring rules D100–D107 are still in the Ruff `ignore` list (`# TODO: Maybe enable these` in `pyproject.toml`). Proposal: enable **D100–D103** (missing docstring in module / class / method / function) for `src` code, and *permanently* ignore D104 (package `__init__.py`), D105 (magic methods), D107 (`__init__` — the class docstring covers construction) plus all of `tests/`, as most projects with strict docstring policies do.

2. Convert the one reST docstring that survived #993: `diracx-routers/tests/health/test_probes.py` still uses `:param:`/`:return:` tags. Ruff doesn't catch it because `convention = "google"` only disables conflicting pydocstyle checks and does not forbid reST tags.

3. Guard against reST tags coming back as it will highly likely try to come back as most of the DIRAC docstrings is using reST. Add a `pygrep` hook to `.pre-commit-config.yaml`:

```yaml
- repo: local
hooks:
- id: forbid-rest-docstrings
name: forbid reST docstring tags (use Google style, see #927)
language: pygrep
entry: '^\s*:(param|type|returns?|rtype|raises?|ivar|cvar|vartype)\b'
types: [python]
exclude: ^diracx-client/src/diracx/client/
```

Suggested migration path (following our [splitting-PRs workflow](https://diracx.diracgrid.org/en/latest/dev/explanations/splitting-prs/), to avoid a repeat of #965):

- Bootstrap PR: fix `test_probes.py`, add the pygrep hook, move the agreed D1xx ignores from the global `ignore` list into `per-file-ignores` entries (one per package, plus permanent exemptions for tests).
- One PR per package (diracx-db and diracx-core are the big ones), each writing the docstrings and deleting that package's `per-file-ignores` entry. Note: that could be a good opportunity to give official **stacked pull request** ([public preview since 2026-07-30](https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-in-public-preview/), `gh extension install github/gh-stack`) a go!

### Definition of Done

- [ ] `test_probes.py` docstring converted to Google style
- [ ] pre-commit hook rejecting reST docstring tags in place
- [ ] Agreed missing-docstring rules (proposed: D100–D103, src only) no longer globally ignored; all packages pass
- [ ] API reference on diracx.diracgrid.org renders without undocumented public objects

### Alternatives Considered

- **Ruff `DOC` rules (pydoclint port)**: would indirectly flag reST docstrings (their sections don't parse as Google, so args/returns count as undocumented), but the rules are preview-only and the signal is indirect. Can be revisited once stable.
- **Standalone [pydoclint](https://github.com/jsh9/pydoclint)** with `--style=google`: also validates docstring/signature consistency, but adds a second linter overlapping Ruff.
- **No automated reST guard** (rely on review): reST now only enters via copy-paste from legacy DIRAC and is easy to spot — but the 5-line hook automates exactly that review comment.
- **One big PR**: already rejected in #965 — too slow to review, constant rebases.

### Related Issues

Related to: #927 (this is the follow-up carved out of it)
See also: #993 (conversion + Ruff convention), #965 (closed: scope grew beyond conversion)

### Additional Context

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.