Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

use the obj role for all See Also items #8051

Merged
merged 5 commits into from Oct 29, 2020
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
28 changes: 28 additions & 0 deletions sphinx/ext/napoleon/docstring.py
Expand Up @@ -1131,6 +1131,11 @@ def _parse_numpydoc_see_also_section(self, content: List[str]) -> List[str]:
func_name1, func_name2, :meth:`func_name`, func_name3

"""
try:
inventory = self._app.builder.env.intersphinx_inventory
except AttributeError:
inventory = {}
keewis marked this conversation as resolved.
Show resolved Hide resolved

items = []

def parse_item_name(text: str) -> Tuple[str, str]:
Expand All @@ -1151,6 +1156,25 @@ def push_item(name: str, rest: List[str]) -> None:
items.append((name, list(rest), role))
del rest[:]

def search_inventory(inventory, name, hint=None):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function is no longer needed now.

roles = list(inventory.keys())
if hint is not None:
preferred = [
role
for role in roles
if role.split(":", 1)[-1].startswith(hint)
]
roles = preferred + [role for role in roles if role not in preferred]

for role in roles:
objects = inventory[role]
found = objects.get(name, None)
if found is not None:
domain, role = role.split(":", 1)
return role

return None

current_func = None
rest = [] # type: List[str]

Expand Down Expand Up @@ -1206,6 +1230,10 @@ def push_item(name: str, rest: List[str]) -> None:
lines = [] # type: List[str]
last_had_desc = True
for func, desc, role in items:
if not role:
raw_role = search_inventory(inventory, func, hint=func_role)
role = roles.get(raw_role, raw_role)

if role:
link = ':%s:`%s`' % (role, func)
elif func_role:
Expand Down
22 changes: 22 additions & 0 deletions tests/test_ext_napoleon_docstring.py
Expand Up @@ -1365,6 +1365,7 @@ def test_see_also_refs(self):

config = Config()
app = mock.Mock()
app.builder.env = None
actual = str(NumpyDocstring(docstring, config, app, "method"))

expected = """\
Expand All @@ -1379,6 +1380,27 @@ def test_see_also_refs(self):
"""
self.assertEqual(expected, actual)

config = Config()
app = mock.Mock()
app.builder.env.intersphinx_inventory = {
"py:func": {"funcs": (), "otherfunc": ()},
"py:meth": {"some": (), "other": ()},
}
actual = str(NumpyDocstring(docstring, config, app, "method"))

expected = """\
numpy.multivariate_normal(mean, cov, shape=None, spam=None)

.. seealso::

:meth:`some`, :meth:`other`, :func:`funcs`
\n\
:func:`otherfunc`
relationship
"""
self.assertEqual(expected, actual)


def test_colon_in_return_type(self):
docstring = """
Summary
Expand Down