Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstring linting to CI #150

Open
Mr0grog opened this issue Dec 13, 2023 · 0 comments
Open

Add docstring linting to CI #150

Mr0grog opened this issue Dec 13, 2023 · 0 comments

Comments

@Mr0grog
Copy link
Member

Mr0grog commented Dec 13, 2023

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:

python -m numpydoc.hooks.validate_docstrings wayback/**/*.py

(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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Backlog
Development

No branches or pull requests

1 participant