numpydoc
numpydoc copied to clipboard
numpy
see also section crashes on :doc:`...`
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.
@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.
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).
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.
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.
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).
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.
Agreed it would be nice to be able to link to any documented object rather than just func/method/class.
