BUG: Object references that start with a tilde in "See Also" section cause a ValueError

[namurphy]

Description

When I ran the docstring validator on a docstring with a "See Also" section that contains an object reference starting with a tilde, I got a ValueError that caused the validator to crash.

This might be related to #232.

Expected behavior

Ideally, an object reference starting with a tilde would be recognized as valid.

Otherwise, if a "See Also" section is not able to be parsed, the validator would ideally keep running and instead report the problem with a specific error code.

It would also have been helpful for the traceback to say which file the error occurred in.

Minimum reproducible example

Using numpydoc 1.6.0:

def test_something():
    """
    Sample docstring.

    See Also
    --------
    ~astropy.units.Quantity
    """
    ...

When I run validate-docstrings on a file containing this function/docstring, then I get the following error:

Traceback (most recent call last):
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/bin/validate-docstrings", line 8, in <module>
sys.exit(main())
^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 400, in main
findings.extend(process_file(file, config_options))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 339, in process_file
docstring_visitor.visit(module_node)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 221, in visit
self.generic_visit(node)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/ast.py", line 426, in generic_visit
self.visit(item)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 219, in visit
self._get_numpydoc_issues(node)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 188, in _get_numpydoc_issues
report = validate.validate(
^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/validate.py", line 613, in validate
doc = validator_cls(obj_name=obj_name, **validator_kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 44, in __init__
self.doc: docscrape.NumpyDocString = docscrape.NumpyDocString(self.raw_doc)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 149, in __init__
self._parse()
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 425, in _parse
self["See Also"] = self._parse_see_also(content)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 344, in _parse_see_also
self._error_location(f"Error parsing See Also entry {line!r}")
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 453, in _error_location
raise ValueError(msg)
ValueError: Error parsing See Also entry '~astropy.units.Quantity'

Thank you!

[namurphy]

I get a similar error for docstrings that contain reStructuredText substitutions (where I'm making use of sphinxcontrib-globalsubs):

def test_something():
    """
    Sample docstring.

    See Also
    --------
    |Quantity|
    """
    ...

Thank you again!

[mhvk]

Another example at https://github.com/numpy/numpy/pull/25416/files#r1434392613 - the validator failed on a .. versionadded:: 2.0.0 line. We just worked around it by adding an Examples section, should have raised an issue!

[j9ac9k]

EDIT: submitted #558 but this only handles the case of the sphinx cross-references.

Similarly I'm having issues with cross-references. See issue for more detail:

pyqtgraph/pyqtgraph#3028 (comment)

This blows up:

See Also
---------
:meth:`QImage.save <QImage.save>`  :
    ...

This is ok (but the rendered result doesn't include the class name which is what I wanted).

See Also
---------
:meth:`QImage.save`  :
    ...

In case it helps, here's the full traceback:

Traceback (most recent call last):
  File "/Users/ogi/.pyenv/versions/pyqtgraph-docs/bin/numpydoc", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/cli.py", line 127, in main
    return func(**args)
           ^^^^^^^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 372, in run_hook
    findings.extend(process_file(file, config_options))
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 338, in process_file
    docstring_visitor.visit(module_node)
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 220, in visit
    self.generic_visit(node)
  File "/Users/ogi/.pyenv/versions/3.11.4/lib/python3.11/ast.py", line 426, in generic_visit
    self.visit(item)
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 220, in visit
    self.generic_visit(node)
  File "/Users/ogi/.pyenv/versions/3.11.4/lib/python3.11/ast.py", line 426, in generic_visit
    self.visit(item)
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 218, in visit
    self._get_numpydoc_issues(node)
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 187, in _get_numpydoc_issues
    report = validate.validate(
             ^^^^^^^^^^^^^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/validate.py", line 626, in validate
    doc = validator_cls(obj_name=obj_name, **validator_kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 43, in __init__
    self.doc: docscrape.NumpyDocString = docscrape.NumpyDocString(self.raw_doc)
                                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/docscrape.py", line 147, in __init__
    self._parse()
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/docscrape.py", line 419, in _parse
    self["See Also"] = self._parse_see_also(content)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/docscrape.py", line 342, in _parse_see_also
    self._error_location(f"Error parsing See Also entry {line!r}")
  File "/Users/ogi/.pyenv/versions/3.11.4/envs/pyqtgraph-docs/lib/python3.11/site-packages/numpydoc/docscrape.py", line 447, in _error_location
    raise ValueError(msg)
ValueError: Error parsing See Also entry ':meth:`QImage.save <QImage.save>` :'