numpydoc.validate fails on the reference docstring example
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
The recently added numpydoc.validate functionality fails on the reference docstring in doc/example.py.
>>> from numpydoc.validate import validate
>>> validate("doc.example.foo")
{'type': 'function',
[...]
'deprecated': False,
'file': '/home/rth/src/numpydoc/doc/example.py',
'file_line': 37,
'errors': [
('GL01',
'Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)'),
('GL02',
'Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)'),
('GL03',
'Double line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstrings'),
('SS06', 'Summary should fit in a single line'),
('RT03', 'Return value has no description'),
('SA02',
'Missing period at end of description for See Also "numpy.array" reference'),
('SA03',
'Description should be capitalized for See Also "numpy.array" reference'),
('SA04', 'Missing description for See Also "numpy.dot" reference'),
('SA04', 'Missing description for See Also "numpy.linalg.norm" reference'),
('SA04', 'Missing description for See Also "numpy.eye" reference')]}
It seems the validator is contradicting some of the docstring formatting rules (e.g. https://github.com/numpy/numpydoc/issues/241)
cc @datapythonista @jnothman @larsoner
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the reference docstring in doc/example.py and run the numpydoc.validate("doc.example.foo") example from the issue. Compare the reported GL01, GL02, GL03, SS06, RT03, SA02, SA03, and SA04 errors with the formatting rules discussed in issue 241; done means the validator and reference example no longer contradict the documented rules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, testing
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100