doclint: reject non-numpydoc docstrings on changed files

[pbrubeck]

Adds make doclint: numpydoc-lints the *.py files changed by a branch against $BASE, catching Sphinx/Google-style docstrings via PR01-PR03. Wired into make lint and CI's lint job (now needs fetch-depth: 0 for the diff). flake8/pylint move into the docs extra so a fresh checkout has something to lint with.

CI passes BASE explicitly (main vs release, from the PR's base/label). Locally, BASE defaults by picking whichever of origin/main/origin/release forked from HEAD more recently.

No code touched, so based on release.

[dham]

How does this work if we need to make a deliberate decision to violate numpydoc in some instance?

[pbrubeck]

How does this work if we need to make a deliberate decision to violate numpydoc in some instance?

I think you can violate numpydoc in this approach. This PR only forbids non-numpydoc in new lines by looking at the diff against main or release (whichever is the closest).

A deliberate violation can be accepted if we "merge with prejudice" even if CI reports a doclint failure. We will not continue to error on historical violations.

As far as I understand, currently there is no step in make lint that checks docstring style. However, when the docs are built, Sphinx was already checking correct use of either numpydoc or the old sphinx docs (:arg x:). Outside the doc build, there was no step in our workflow that checked docstring style.

However, if we want mechanism, not policy, we can have loud warnings instead of failures, with the hope that a human or LLM contributor cares enough to address them. But if our code contribution guide says this is our policy, it'd be good for it to be enforced automatically, to allow the review to be focused on the Mathematics and the actual purpose of the code.

[pbrubeck]

What do we want to keep from here?

GL06: The docstring contains unauthorized or misspelled section headers.
GL07: The structural sections are placed in the incorrect chronological order.
PR01: Parameters defined in the function signature are completely missing from the documentation.
PR02: The parameters section documents a variable name that does not exist in the code.
PR03: The documented parameters do not match the exact order of the function signature.
SS03: The summary line or first sentence is missing a closing period.
SS05: The short summary fails to begin with a command-style infinitive verb.

[connorjward]

_version.py does not exist

[connorjward]

As soon as someone modifies mesh.py they are going to be very sad if we run against changed files...

I would think that changing RST to numpydoc is something an LLM could actually do very very easily. Someone would have to read it all and make sure that everything was transferred correctly.

[pbrubeck]

As soon as someone modifies mesh.py they are going to be very sad if we run against changed files...

The idea is to run against changed lines. This is the exact same policy we have: any docstrings that are included in a diff must be promoted to numpydoc

[connorjward]

As soon as someone modifies mesh.py they are going to be very sad if we run against changed files...

The idea is to run against changed lines. This is the exact same policy we have: any docstrings that are included in a diff must be promoted to numpydoc

I don't see how

git diff --name-only --diff-filter=ACM $(BASE)...HEAD -- '*.py'

filters only changed lines. It appears to work file-wise.

[pbrubeck]

As soon as someone modifies mesh.py they are going to be very sad if we run against changed files...

The idea is to run against changed lines. This is the exact same policy we have: any docstrings that are included in a diff must be promoted to numpydoc

I don't see how

git diff --name-only --diff-filter=ACM $(BASE)...HEAD -- '*.py'

filters only changed lines. It appears to work file-wise.

Right, that was my oversight. But it appears that ruff can be used selectively on modified lines.