What is the spec for "See Also" in docstrings?
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
scipy/scipy#8702 shows an example where a line with multiple function names prior to the colon (:) loses all text after the colon.
See Also
--------
scipy.stats.kstwobign : Provides the functionality as a continuous distribution
smirnov, smirnovi, smirnovc, smirnovci, smirnovp : Functions for the one-sided distribution
generates a block looking like
See Also:
scipy.stats.kstwobign Provides the functionality as a continuous distribution
smirnov, smirnovi, smirnovc, smirnovci, smirnovp
The text "Functions for the one-sided distribution" has completely disappeared from the output.
Also the last line, while inside the HTML <div> ... </div> block, is in a separate paragraph.
Q. What is the spec for the See Also block?
I found an implementation inside NumpyDocString._parse_see_also() in numpydoc/docscrape.py. It appears to accept:
<FUNCNAME><FUNCNAME> <SPACE>* : <DESCRIPTION><FUNCNAME> , <FUNCNAME>
but not<FUNCNAME> , <FUNCNAME> SPACE* : <DESCRIPTION>
Is the dropping of the DESCRIPTION in the last one intentional, or an unintended side-effect of the particular regexes used?
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 NumpyDocString._parse_see_also() in numpydoc/docscrape.py and compare its handling of the four See Also forms shown in the issue. Determine the intended spec for grouped names with a description, then establish the expected output and verify that descriptions and paragraph structure are handled consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100