From 1e61a5335e350fd2a76b1e3af2bc48b3727d4d18 Mon Sep 17 00:00:00 2001
From: Ognyan Moore <ognyan.moore@gmail.com>
Date: Tue, 21 May 2024 22:26:19 -0400
Subject: [PATCH 1/2] See Also Parser Recognizes Sphinx XREF

The See Also section raises a ValueError when it encounters a valid
sphinx cross-reference such as :meth:`QImage.save <QImage.save>`

This commit allows the regex to parse the sphinx target, which is the
section between the angled brackets.
---
 numpydoc/docscrape.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py
index 26a08259..3a5db4ce 100644
--- a/numpydoc/docscrape.py
+++ b/numpydoc/docscrape.py
@@ -256,14 +256,16 @@ def _parse_param_list(self, content, single_element_is_type=False):
     # <FUNCNAME> is one of
     #   <PLAIN_FUNCNAME>
     #   COLON <ROLE> COLON BACKTICK <PLAIN_FUNCNAME> BACKTICK
+    #   COLON <ROLE> COLON BACKTICK <PLAIN_FUNCNAME> RIGHT_ANGLE_BRACKET <TARGET_NAME> LEFT_ANGLE_BRACKET BACKTICK
     # where
+    #   <TARGET_NAME> is a legal sphinx target for cross-linking
     #   <PLAIN_FUNCNAME> is a legal function name, and
     #   <ROLE> is any nonempty sequence of word characters.
-    # Examples: func_f1  :meth:`func_h1` :obj:`~baz.obj_r` :class:`class_j`
+    # Examples: func_f1  :meth:`func_h1` :obj:`~baz.obj_r` :class:`class_j` :class:`class_j <class_j>`
     # <DESC> is a string describing the function.
 
     _role = r":(?P<role>(py:)?\w+):"
-    _funcbacktick = r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`"
+    _funcbacktick = r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)\s?(?P<target_name>(?:\s?\<\w)[a-zA-Z0-9_\.-]+(?:\>))?`"
     _funcplain = r"(?P<name2>[a-zA-Z0-9_\.-]+)"
     _funcname = r"(" + _role + _funcbacktick + r"|" + _funcplain + r")"
     _funcnamenext = _funcname.replace("role", "rolenext")
@@ -299,7 +301,7 @@ def _parse_see_also(self, content):
         items = []
 
         def parse_item_name(text):
-            """Match ':role:`name`' or 'name'."""
+            """Match ':role:`name`', ':role:`name <target>`' or 'name'."""
             m = self._func_rgx.match(text)
             if not m:
                 self._error_location(f"Error parsing See Also entry {line!r}")

From 4945fe2ea066575c84688e1864859ab7c6c1d5c3 Mon Sep 17 00:00:00 2001
From: Ognyan Moore <ognyan.moore@gmail.com>
Date: Wed, 5 Mar 2025 05:00:08 +0300
Subject: [PATCH 2/2] Incorporate target_name into test suite.

---
 numpydoc/docscrape.py            | 4 ++++
 numpydoc/tests/test_docscrape.py | 5 +++++
 2 files changed, 9 insertions(+)

diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py
index 3a5db4ce..81a0b0c2 100644
--- a/numpydoc/docscrape.py
+++ b/numpydoc/docscrape.py
@@ -307,6 +307,10 @@ def parse_item_name(text):
                 self._error_location(f"Error parsing See Also entry {line!r}")
             role = m.group("role")
             name = m.group("name") if role else m.group("name2")
+
+            target_name = m.group("target_name")
+            if target_name is not None:
+                name += f" {target_name}"
             return name, role, m.end()
 
         rest = []
diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py
index acf5194c..8a8e5e19 100644
--- a/numpydoc/tests/test_docscrape.py
+++ b/numpydoc/tests/test_docscrape.py
@@ -109,6 +109,7 @@
   some, other, funcs
   otherfunc : relationship
   :py:meth:`spyder.widgets.mixins.GetHelpMixin.show_object_info`
+  :py:meth:`int.bit_length <int.bit_length>`
 
   Examples
   --------
@@ -456,6 +457,8 @@ def test_str(doc):
     relationship
 :py:meth:`spyder.widgets.mixins.GetHelpMixin.show_object_info`
     ..
+:py:meth:`int.bit_length <int.bit_length>`
+    ..
 
 Notes
 -----
@@ -647,6 +650,8 @@ def test_sphinx_str():
         relationship
     :py:meth:`spyder.widgets.mixins.GetHelpMixin.show_object_info`
         ..
+    :py:meth:`int.bit_length <int.bit_length>`
+        ..
 
 .. rubric:: Notes