Shorter section underlines trigger ambiguous validation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
While testing #454 I noticed that for the following docstring,
"""Bad, bad docstring!
Parameters
---------
x : `int`
y:
Another variable.
Returns
-------
z : `int`
The sum of ``x`` and ``y``.
"""
which contains many issues, but the issue of the shorter underline triggers a rather misterious
PR01 | Parameters {'x', 'y'} not documented.
In fact, after adding the missing dash I get the next issues, PR01, PR02, PR07 and PR10.
From the list of available validation checks the shorter underline problem is not present, I guess because it's more an RsT issue, but since numpydoc uses RsT (unless I overlooked this), I think it should be a proper validation check.
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 by reproducing the docstring example and reviewing the validation checks listed in the linked numpydoc validation documentation. Trace how the malformed section underline is reported, then add coverage so it is identified distinctly from parameter-documentation errors and verify the resulting validation messages.
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
- 42/100