numpydoc pre-commit hook

[jdeschamps]

Add numpydoc pre-commit hook to enforce numpy docstring format.

Started using this and I am pretty happy with it. There are however some hiccups with mkdocstring, which I have not really examined yet (e.g. md lists not formatted).

[tlambert03]

We already have ruff doing something similar: https://docs.astral.sh/ruff/rules/#pydocstyle-d

And https://docs.astral.sh/ruff/settings/#pydocstyle

What need were you finding that this additional hook fills?

[jdeschamps]

Yes, sorry I overlooked that part a little bit.

[EDIT]: Let's do things properly, I moved my answer to #18.

[jdeschamps]

New behaviour:

use_ruff:
  when: "{{ mode == 'customize' and use_pre_commit }}"
  type: bool
  help: Add ruff for linting?
  default: "{{ mode != 'simple' }}"

use_pydocstyle:
  when: "{{ mode == 'customize' and use_pre_commit and use_ruff }}"
  type: bool
  help: Use pydocstyle (via ruff) for checking documentation compliance?
  default: "{{ use_ruff }}"

use_numpydoc:
  when: "{{ mode == 'customize' and use_pre_commit and not use_pydocstyle }}"
  type: bool
  help: Use numpydoc for checking documentation compliance?
  default: "{{ not use_pydocstyle and mode != 'simple'}}"

pydocstyle and numpydoc are mutually exclusive, and only available if use_pre_commit == True (for both) and use_ruff == True (pycodestyle).

They are both not present in "Simple" mode, and only pydocstyle is set in "Fully featured".

The awkward thing right now is that when choosing pydocstyle, one doesn't know about numpydoc. One could modify the pydocstyle question to mention numpydoc.

[tlambert03]

looking good.

The awkward thing right now is that when choosing pydocstyle, one doesn't know about numpydoc. One could modify the pydocstyle question to mention numpydoc.

yeah, perhaps instead of the two-step process, you could use choices:

something like

docstring_linter:
    when: "{{ mode == 'customize' and use_pre_commit }}"
    type: str
    choices:
        Use pydocstyle (via ruff): pydocstyle
        Use numpydoc: numpydoc
        no docstring linter: null

i guess if they said "no ruff" though, it would be best to remove the (via ruff) option... haven't checked whether you can make the set of choices conditional

[jdeschamps]

Makes a looot more sense. I'll check it out!

[tlambert03]

mind if i close this? :)

[jdeschamps]

Nope!