numpy / numpy/numpydoc

numpydoc.validate fails on the reference docstring example

Open
#242 5 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.