numpy / numpy/numpydoc

What is the spec for "See Also" in docstrings?

Open
#170 9 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

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:

  1. <FUNCNAME>
  2. <FUNCNAME> <SPACE>* : <DESCRIPTION>
  3. <FUNCNAME> , <FUNCNAME>
    but not
  4. <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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.