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

Activity

1. namurphy

   changed the title [-]BUG: Object references that start with a tilde in "See Also section" cause a `ValueError`[/-] [+]BUG: Object references that start with a tilde in "See Also" section cause a `ValueError`[/+] on Dec 22, 2023
2. namurphy commented on Dec 22, 2023

   

   namurphy

   on Dec 22, 2023

   Last edited by namurphy

   ContributorAuthor

   More actions

   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!
3. mhvk commented on Dec 27, 2023

   

   mhvk

   on Dec 27, 2023

   More actions

   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!

   👍React with 👍1Reacted by Nick Murphy
4. j9ac9k commented on May 21, 2024

   

   j9ac9k

   on May 21, 2024

   Last edited by j9ac9k

   More actions

   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>` :'