(It is kinda weird that the only way to run it against a set of files is with the CLI entrypoint designed for git pre-commit hooks, but the only other CLI entrypoint takes a path to a single Python symbol which isn’t really useful here. 🤷)
It would be nice to add this to our linting job in CI. Bonus points for figuring out how to reformat the output for GitHub to show annotations in a PR’s diff view (the out-of-the-box format is not correct for this) (also getting the inline annotations to show up is easier in a GitHub actions workflow, and I am fine if you want to do that instead of adding to the CircleCI job — it’s not ideal, but it works).
This already throws off a lot of warnings, some of which we should address and others we should probably disable because we don’t care (e.g. SA01, not every docstring needs a “see also” section).
I recently learned that numpydoc (which is what we use for our docstrings) has a validation/linting feature built-in: https://numpydoc.readthedocs.io/en/latest/validation.html
It can be run as part of a Sphinx build or on its own:
(It is kinda weird that the only way to run it against a set of files is with the CLI entrypoint designed for git pre-commit hooks, but the only other CLI entrypoint takes a path to a single Python symbol which isn’t really useful here. 🤷)
It would be nice to add this to our linting job in CI. Bonus points for figuring out how to reformat the output for GitHub to show annotations in a PR’s diff view (the out-of-the-box format is not correct for this) (also getting the inline annotations to show up is easier in a GitHub actions workflow, and I am fine if you want to do that instead of adding to the CircleCI job — it’s not ideal, but it works).
This already throws off a lot of warnings, some of which we should address and others we should probably disable because we don’t care (e.g.
SA01, not every docstring needs a “see also” section).