see also section crashes on :doc:`...`

[anntzer]

foobar.py:

def main():
    """
    Some fooings, refer to :ref:`the-title` and :doc:`/index`.

    See Also
    --------
    :ref:`the-title`
    :doc:`/index`
    """

index.rst

.. _the-title:

Welcome to foo's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule:: foobar
   :members:

Building with sphinx 2.2.0, numpydoc 0.9.1 crashes on the :doc: entry in the see also section with

"numpydoc.docscrape.ParseError: :doc:`/index` is not a item name in 'Some fooings, refer to :ref:`the-title` and :doc:`/index`.\n\nSee Also\n--------\n:ref:`the-title`\n:doc:`/index`'"

even though in the main text both the :ref: and the :doc: work fine and the :ref: works fine in the See Also section as well.

[jnothman]

If you switch the order of the ref and doc items, is the error the same?

[anntzer]

yes (it's still :doc: that fails)

[rossbar]

@anntzer Are you still having this issue? I tried your example and I think the problem is the forward slash on /index. If you remove the / all build errors disappear and the resulting page and links appear to be correct.

[anntzer]

Yes, I still have the issue when using the leading slash, which is explicitly allowed by sphinx (http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc).

[rossbar]

In that case, the issue appears to be with _line_rgx failing to match when a forward slash is present.

> /home/ross/.virtualenvs/numpydoc/lib/python3.7/site-packages/numpydoc-1.0.0.dev0-py3.7.egg/numpydoc/docscrape.py(303)_parse_see_also()               
-> description = None                                                                                                                                  
(Pdb) l                                                                                                                                                
298                 if not line.strip():                                                                                                               
299                     continue                                                                                                                       
300                                                                                                                                                    
301                 line_match = self._line_rgx.match(line)                                                                                            
302                 pdb.set_trace()                                                                                                                    
303  ->             description = None                                                                                                                 
304                 if line_match:                                                                                                                     
305                     description = line_match.group('desc')                                                                                         
306                     if line_match.group('trailing') and description:                                                                               
307                         self._error_location(                                                                                                      
308                             'Unexpected comma or period after function list at index %d of '                                                       
(Pdb) line_match                                                                                                                                       
<re.Match object; span=(0, 16), match=':ref:`the-title`'>                                                                                              
(Pdb) c                                                                                                                                                
> /home/ross/.virtualenvs/numpydoc/lib/python3.7/site-packages/numpydoc-1.0.0.dev0-py3.7.egg/numpydoc/docscrape.py(302)_parse_see_also()               
-> pdb.set_trace()                                                                                                                                     
(Pdb) line_match                                                                                                                                       
(Pdb)            

_line_rgx matches with the :doc: line when the forward slash is not present. I'm far from an expert in regular expressions, but perhaps _line_rgx needs to be modified to match when forwards slashes are present.

[rossbar]

According to the comments in lines 239-253 of docscrape.py and the numpydocs documentation, it seems that the see also section is only intended for references to other functions (or methods, objects, and classes) rather than references to documentation.

[anntzer]

It would be nice if it matched the features of sphinx's own .. seealso::, which supports refering to general items (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-seealso).

[rossbar]

That's a good point - it seems that see also is the only direct naming collision between the supported sphinx directives and the numpydocs sections. Maybe @jnothman and other maintainers could weigh-in on whether the See Also section should support more general references.

[larsoner]

Agreed it would be nice to be able to link to any documented object rather than just func/method/class.