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

[pvanmulbregt]

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?

[jnothman]

I don't know its history, but if it's easy to get something that handles that case and renders well, we should probably support it. and if not, we should probably tell the user their markup isn't supported

[jorisvandenbossche]

+ 1 to actually supporting that syntax, and not dropping the description (although a warning/error would certainly also be an improvement). I also encountered this in the pandas docs.

[pvanmulbregt]

I have some changes to docscrape.py that extend it to accept

    See Also
    --------
    otherfunc : relationship (optional)
    newfunc : Relationship (optional), which could be fairly long, in which
              case the line wraps here.
    funcsix, funcseven : 6 and 7 description
    thirdfunc, fourthfunc, fifthfunc
    funceight : more stuff

so that the rendered HTML looks like

Ideally there would be one description list (<dl>) block, but it appears that whatever processes the output of docscrape is applying its own logic so that there are two different<dl> blocks (covering the first 3 entries and the last entry respectively), and a separate intervening paragraph with thirdfunc, fourthfunc and fifthfunc, all lying within the same <div> block.

The modifications to docscrape.py produce

'.. rubric:: See Also'                                                                                                                           
''
''
':obj:`otherfunc`'
'    relationship (optional)'
':obj:`newfunc`'
'    Relationship (optional), which could be fairly long, in which case the line wraps here.'
':obj:`funcsix`, :obj:`funcseven`'
'    6 and 7 description'
':obj:`thirdfunc`, :obj:`fourthfunc`, :obj:`fifthfunc`'
''
':obj:`funceight`'
'    more stuff'
''
''

but the post-docscrape processing doesn't treat the empty strings as empty <dd> items for a list definition, but instead uses them to stop the list definition.

Here's the HTML

<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="docutils">
<dt><code class="xref py py-obj docutils literal"><span class="pre">otherfunc</span></code></dt>
<dd>relationship (optional)</dd>
<dt><code class="xref py py-obj docutils literal"><span class="pre">newfunc</span></code></dt>
<dd>Relationship (optional), which could be fairly long, in which case the line wraps here.</dd>
<dt><code class="xref py py-obj docutils literal"><span class="pre">funcsix</span></code>, <code class="xref py py-obj docutils literal"><span class="pre">funcseven</span></code></dt>
<dd>6 and 7 description</dd>
</dl>
<p><code class="xref py py-obj docutils literal"><span class="pre">thirdfunc</span></code>, <code class="xref py py-obj docutils literal"><span class="pre">fourthfunc</span></code>, <code class="xref py py-obj docutils literal"><span class="pre">fifthfunc</span></code></p>
<dl class="last docutils">
<dt><code class="xref py py-obj docutils literal"><span class="pre">funceight</span></code></dt>
<dd>more stuff</dd>
</dl>
</div>

Is there a way to tell sphinx/numpydoc to create a description list entry with an empty description?

[jnothman]

we have similar handling of empty description in _str_param_list. you just need to create a comment as a description.

On 13 Apr 2018 6:28 am, "Paul van Mulbregt" [email protected] wrote:

I have some changes to docscrape.py that extend it to accept

See Also
--------
otherfunc : relationship (optional)
newfunc : Relationship (optional), which could be fairly long, in which
          case the line wraps here.
funcsix, funcseven : 6 and 7 description
thirdfunc, fourthfunc, fifthfunc
funceight : more stuff

so that the rendered HTML looks like [image: screen shot 2018-04-12 at 3 57 56 pm] https://user-images.githubusercontent.com/23403152/38700857-5bd6bc42-3e6a-11e8-9838-4c1380562102.png

Ideally there would be one description list (

) block, but it appears that whatever processes the output of docscrape is applying its own logic so that there are two different

blocks (covering the first 3 entries and the last entry respectively), and a separate intervening paragraph with thirdfunc, fourthfunc and fifthfunc, all lying within the same

block.

The modifications to docscrape.py produce

'.. rubric:: See Also' '' '' ':obj:otherfunc' ' relationship (optional)' ':obj:newfunc' ' Relationship (optional), which could be fairly long, in which case the line wraps here.' ':obj:funcsix, :obj:funcseven' ' 6 and 7 description' ':obj:thirdfunc, :obj:fourthfunc, :obj:fifthfunc' '' ':obj:funceight' ' more stuff' '' ''

but the post-docscrape processing doesn't treat the empty strings as empty

items for a list definition, but instead uses them to stop the list definition.

Here's the HTML

See also

otherfunc

relationship (optional)

newfunc

Relationship (optional), which could be fairly long, in which case the line wraps here.

funcsix, funcseven

6 and 7 description

thirdfunc, fourthfunc, fifthfunc

funceight

more stuff

Is there a way to tell sphinx/numpydoc to create a description list entry with an empty description?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/numpy/numpydoc/issues/170#issuecomment-380934194, or mute the thread https://github.com/notifications/unsubscribe-auth/AAEz608fR67X6ZeZx8wncPvc7KYVOwTeks5tn7jTgaJpZM4TQ0IM .

[pvanmulbregt]

Thanks @jnothman. What do you mean by "a comment as a description"? I experimented with no comments, empty comments, and comments with only spaces, and all were dumped by the time the HTML was generated. A comment of ' \u200B' survived long enough to keep the <dl> block going, at least in Py3.

Do the Parameters/Returns etc blocks go through the same processing as the See Also block? The Parameters seem to generate <p class="first last"> and <dl class="first docutils"> HTML, whereas See Also generates <dl class="last docutils"> HMTL, suggesting different downstream processing.

[jnothman]

https://github.com/numpy/numpydoc/blob/de21addd6560576151938a4bc59543d55ce6f085/numpydoc/docscrape_sphinx.py#L215

[jnothman]

I'm not really able to look in more detail now

[pvanmulbregt]

Thanks. That kept everything within a singe <dl> block.

The rendered <div> block doesn't contain all the text, and the descriptions don't line up with the functions, but that may be a different issue.

    See Also
    --------
    otherfunc : relationship (optional)
    newfunc : Relationship (optional), which could be fairly long, in which
              case the line wraps here.
    thirdfunc, fourthfunc, fifthfunc
    sixf, sevenf : stuff
        more stuff

renders as

The HTML looks OK, but the display is misaligned.

<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><code class="xref py py-obj docutils literal"><span class="pre">otherfunc</span></code></dt>
<dd>relationship (optional)</dd>
<dt><code class="xref py py-obj docutils literal"><span class="pre">newfunc</span></code></dt>
<dd>Relationship (optional), which could be fairly long, in which case the line wraps here.</dd>
<dt><code class="xref py py-obj docutils literal"><span class="pre">thirdfunc</span></code>, <code class="xref py py-obj docutils literal"><span class="pre">fourthfunc</span></code>, <code class="xref py py-obj docutils literal"><span class="pre">fifthfunc</span></code></dt>
<dd></dd>
<dt><code class="xref py py-obj docutils literal"><span class="pre">sixf</span></code>, <code class="xref py py-obj docutils literal"><span class="pre">sevenf</span></code></dt>
<dd>stuff more stuff</dd>
</dl>
</div>

[jnothman]

that will depend on stylesheet, I assume, which isn't numpydoc's business. Good to have this fix. I'll try to review eventually!