You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I tried out numpydoc on PlasmaPy recently and ran into a problem (numpy/numpydoc#519) where the crashed with an exception, rather than noting that the problem was with a specific rule. I'm waiting until this issue gets fixed before adding numpydoc to pre-commit.
This particular error happens when a line in a See Also section starts with a ~, `~, or |. I ran validate-docstring on Astropy's source code just now and ran into the same issue.
so how can we solve this problem? What is the solution?
Numpydoc has a pre-commit we can use. Numpydoc uses a config file specifying what error codes to check. We'd want to start by turning off any that we are currently failing then sequentially turn them on and fix the issues.
Yes we use it in reproject and it has found countless real issues so I am very much in favour of doing this. It is going to be a lot of work to fix issues!
Reacted by Nathaniel Starkman, Nick Murphy and Clément Robert
In short, this would not be made obsolete by typing because numpydoc checks docstrings, which typing does not interact with. Longer answer is in 3-4 years kinda because Python is adding the typing.Doc annotation and it will be possible to build descriptive docstrings from type annotations, but even then there will be room for Numpydoc (to check the format of all the sections not built from typing.Doc, e.g. Notes, References, etc.).
Yeah, I've played around with it and it is interesting. On the downside, basically all function signatures become 1 parameter per line because of the attached string description. On the upsides: 1) docstrings are guaranteed to be in sync with the function arguments; 2) IDEs can surface descriptive information, not just type hints, about a Parameter on hover-over, 3) it's easier to switch docstring formats, like numpy to google (though I'm not sure why one would want to switch, but it is easier).
Had a look too and really like the idea of doc'd arguments (and class variables, allowing us to remove the sphinx-only docstrings under them). Indeed, I'd go as far as this being something that would actually convince me to use typing myself... (and maybe to have typing_extensions as a required dependency...)
I think for one-line argument docs, the length issue is OK, but for multi-line I'm less sure. More generally, the really descriptive part of an argument, of how it influences the function/method, may still belong in the docstring -- this may need some thought (sadly).
Given that using Doc may well lead to a bit of a rethink of docstrings, I think the case for having numpydoc pre-commit is weakened; we don't want to go through such mini-edits multiple times.
Activity
eerovaher commentedon Sep 26, 2023
Is this supposed to replace
docformatter?nstarman commentedon Sep 26, 2023
They shouldn't be mutually incompatible, but yes that would be the hope.
numpydochas many more specific checks.namurphy commentedon Dec 27, 2023
I tried out numpydoc on PlasmaPy recently and ran into a problem (numpy/numpydoc#519) where the crashed with an exception, rather than noting that the problem was with a specific rule. I'm waiting until this issue gets fixed before adding numpydoc to pre-commit.
This particular error happens when a line in a
See Alsosection starts with a~,`~, or|. I ranvalidate-docstringon Astropy's source code just now and ran into the same issue.mhvk commentedon Dec 27, 2023
Ah, that explains what happened at https://github.com/numpy/numpy/pull/25416/files#r1434272271 - I added a comment to your
numpydocissue as well.pllim commentedon Jan 3, 2024
What kind of correctness? We already have RTD set to turn warning into errors. Is that not enough?
astrofrog commentedon Jan 4, 2024
This will do things like check that all arguments are documented, etc
tactipus commentedon Jan 4, 2024
so how can we solve this problem? What is the solution?
nstarman commentedon Jan 4, 2024
Numpydoc has a pre-commit we can use. Numpydoc uses a config file specifying what error codes to check. We'd want to start by turning off any that we are currently failing then sequentially turn them on and fix the issues.
astrofrog commentedon Jan 4, 2024
Yes we use it in reproject and it has found countless real issues so I am very much in favour of doing this. It is going to be a lot of work to fix issues!
pllim commentedon Jan 4, 2024
But would this be obsolete with the typing stuff taking over in the future?
nstarman commentedon Jan 5, 2024
In short, this would not be made obsolete by typing because numpydoc checks docstrings, which typing does not interact with. Longer answer is in 3-4 years kinda because Python is adding the
typing.Docannotation and it will be possible to build descriptive docstrings from type annotations, but even then there will be room for Numpydoc (to check the format of all the sections not built fromtyping.Doc, e.g.Notes,References, etc.).namurphy commentedon Jan 5, 2024
I hadn't heard about
typing.Docbut it sounds cool! Here's the draft of PEP 727 which is proposingtyping.Docwith a target version of Python 3.13.nstarman commentedon Jan 5, 2024
Yeah, I've played around with it and it is interesting. On the downside, basically all function signatures become 1 parameter per line because of the attached string description. On the upsides: 1) docstrings are guaranteed to be in sync with the function arguments; 2) IDEs can surface descriptive information, not just type hints, about a Parameter on hover-over, 3) it's easier to switch docstring formats, like
numpytogoogle(though I'm not sure why one would want to switch, but it is easier).mhvk commentedon Jan 5, 2024
Had a look too and really like the idea of doc'd arguments (and class variables, allowing us to remove the sphinx-only docstrings under them). Indeed, I'd go as far as this being something that would actually convince me to use typing myself... (and maybe to have
typing_extensionsas a required dependency...)I think for one-line argument docs, the length issue is OK, but for multi-line I'm less sure. More generally, the really descriptive part of an argument, of how it influences the function/method, may still belong in the docstring -- this may need some thought (sadly).
Given that using
Docmay well lead to a bit of a rethink of docstrings, I think the case for having numpydoc pre-commit is weakened; we don't want to go through such mini-edits multiple times.pllim commentedon Sep 9, 2026
Follow-up issue is #20353