diff --git a/CHANGELOG.md b/CHANGELOG.md index c13779d6..f3b349c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,11 @@ ## Unreleased: pdoc next +- Do not shorten `current_module.func` to `func` in docstrings when linking. + This prevents logical errors in code examples with imports. + ([#740](https://github.com/mitmproxy/pdoc/pull/740), @mhils) - Add support for Python 3.13. + ([#730](https://github.com/mitmproxy/pdoc/pull/730), @mhils) - pdoc now strips `collections.abc.` from type annotations to make them more concise. ([#736](https://github.com/mitmproxy/pdoc/pull/736), @mhils) diff --git a/pdoc/render_helpers.py b/pdoc/render_helpers.py index 56d69d54..b87c30dc 100644 --- a/pdoc/render_helpers.py +++ b/pdoc/render_helpers.py @@ -307,11 +307,17 @@ def module_candidates(identifier: str, current_module: str) -> Iterable[str]: @pass_context -def linkify(context: Context, code: str, namespace: str = "") -> str: +def linkify( + context: Context, code: str, namespace: str = "", shorten: bool = True +) -> str: """ Link all identifiers in a block of text. Identifiers referencing unknown modules or modules that are not rendered at the moment will be ignored. A piece of text is considered to be an identifier if it either contains a `.` or is surrounded by `` tags. + + If `shorten` is True, replace identifiers with short forms where possible. + For example, replace "current_module.Foo" with "Foo". This is useful for annotations + (which are verbose), but undesired for docstrings (where we want to preserve intent). """ def linkify_repl(m: re.Match): @@ -381,12 +387,15 @@ def linkify_repl(m: re.Match): and (target_object is doc.obj or target_object is None) and context["is_public"](doc).strip() ): - if module == mod: - url_text = qualname + if shorten: + if module == mod: + url_text = qualname + else: + url_text = doc.fullname + if plain_text.endswith("()"): + url_text += "()" else: - url_text = doc.fullname - if plain_text.endswith("()"): - url_text += "()" + url_text = plain_text return f'{url_text}' # No matches found. diff --git a/pdoc/templates/default/module.html.jinja2 b/pdoc/templates/default/module.html.jinja2 index 458a7985..d1acf56e 100644 --- a/pdoc/templates/default/module.html.jinja2 +++ b/pdoc/templates/default/module.html.jinja2 @@ -209,7 +209,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an {% enddefaultmacro %} {% defaultmacro docstring(var) %} {% if var.docstring %} -
{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}
+
{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname, shorten=False) }}
{% endif %} {% enddefaultmacro %} {% defaultmacro nav_members(members) %} diff --git a/test/testdata/demopackage.html b/test/testdata/demopackage.html index 82c56571..d465c0ff 100644 --- a/test/testdata/demopackage.html +++ b/test/testdata/demopackage.html @@ -263,7 +263,7 @@

-

This class is defined in demopackage.child_c and inherits from B.

+

This class is defined in demopackage.child_c and inherits from .child_b.B.

@@ -331,9 +331,9 @@
Inherited Members

We want to make sure that these links render:

diff --git a/test/testdata/demopackage_dir.html b/test/testdata/demopackage_dir.html index ee3af9e5..66e580f3 100644 --- a/test/testdata/demopackage_dir.html +++ b/test/testdata/demopackage_dir.html @@ -816,7 +816,7 @@

-

This class is defined in demopackage.child_c and inherits from B.

+

This class is defined in demopackage.child_c and inherits from .child_b.B.

@@ -884,9 +884,9 @@
Inherited Members

We want to make sure that these links render:

@@ -1247,14 +1247,14 @@

A sub-package.

-

It imports and re-exposes B, and links to demopackage.C .

+

It imports and re-exposes ..child_b.B, and links to ..C .

-

It also exposes G. These links should all point to the local instance:

+

It also exposes .child_g.G. These links should all point to the local instance:

@@ -1699,8 +1699,8 @@

@@ -2044,7 +2044,7 @@

-

This class is defined in demopackage.child_c and inherits from demopackage.B.

+

This class is defined in demopackage.child_c and inherits from .child_b.B.

diff --git a/test/testdata/top_level_reimports.html b/test/testdata/top_level_reimports.html index b58ebf9f..c1bb2880 100644 --- a/test/testdata/top_level_reimports.html +++ b/test/testdata/top_level_reimports.html @@ -63,10 +63,10 @@

Test that objects re-exposed from an internal module are properly interlinked if they appear on the same page.