do not shorten identifiers in docstrings, fix mitmproxy#739

Author: mhils

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ## Unreleased: pdoc next
 
+- Do not shorten `current_module.func` to `func` in docstrings when linking.
+  This prevents logical errors in code examples with imports.
 - Add support for Python 3.13.
 - pdoc now strips `collections.abc.` from type annotations to make them more concise.
   ([#736](https://github.com/mitmproxy/pdoc/pull/736), @mhils)

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 `<code>` 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'<a href="{relative_link(context["module"].modulename, doc.modulename)}#{qualname}">{url_text}</a>'
 
         # No matches found.

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 %}
-        <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
+        <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname, shorten=False) }}</div>
     {% endif %}
 {% enddefaultmacro %}
 {% defaultmacro nav_members(members) %}

test/testdata/demopackage.html

@@ -263,7 +263,7 @@ <h1 class="modulename">
 </span></pre></div>
 
 
-            <div class="docstring"><p>This class is defined in <a href="demopackage/child_c.html">demopackage.child_c</a> and inherits from <a href="#B">B</a>.</p>
+            <div class="docstring"><p>This class is defined in <a href="demopackage/child_c.html">demopackage.child_c</a> and inherits from <a href="#B">.child_b.B</a>.</p>
 </div>
 
 
@@ -331,9 +331,9 @@ <h5>Inherited Members</h5>
 <p>We want to make sure that these links render:</p>
 
 <ul>
-<li><a href="#G">G</a></li>
-<li><a href="#G">G</a></li>
-<li><a href="#G">G</a></li>
+<li><a href="#G">demopackage.G</a></li>
+<li><a href="#G">demopackage.subpackage.G</a></li>
+<li><a href="#G">demopackage.subpackage.child_g.G</a></li>
 </ul>
 </div>
 

test/testdata/demopackage_dir.html

@@ -816,7 +816,7 @@ <h1 class=&quot;modulename&quot;>
 </span></pre></div>
 
 
-            <div class=&quot;docstring&quot;><p>This class is defined in <a href=&quot;demopackage/child_c.html&quot;>demopackage.child_c</a> and inherits from <a href=&quot;#B&quot;>B</a>.</p>
+            <div class=&quot;docstring&quot;><p>This class is defined in <a href=&quot;demopackage/child_c.html&quot;>demopackage.child_c</a> and inherits from <a href=&quot;#B&quot;>.child_b.B</a>.</p>
 </div>
 
 
@@ -884,9 +884,9 @@ <h5>Inherited Members</h5>
 <p>We want to make sure that these links render:</p>
 
 <ul>
-<li><a href=&quot;#G&quot;>G</a></li>
-<li><a href=&quot;#G&quot;>G</a></li>
-<li><a href=&quot;#G&quot;>G</a></li>
+<li><a href=&quot;#G&quot;>demopackage.G</a></li>
+<li><a href=&quot;#G&quot;>demopackage.subpackage.G</a></li>
+<li><a href=&quot;#G&quot;>demopackage.subpackage.child_g.G</a></li>
 </ul>
 </div>
 
@@ -1247,14 +1247,14 @@ <h1 class=&quot;modulename&quot;>
 
                         <div class=&quot;docstring&quot;><p>A sub-package.</p>
 
-<p>It imports and re-exposes <a href=&quot;#B&quot;>B</a>, and links to <code><a href=&quot;../demopackage.html#C&quot;>demopackage.C</a></code> .</p>
+<p>It imports and re-exposes <a href=&quot;#B&quot;>..child_b.B</a>, and links to <code><a href=&quot;../demopackage.html#C&quot;>..C</a></code> .</p>
 
-<p>It also exposes <a href=&quot;#G&quot;>G</a>. These links should all point to the local instance:</p>
+<p>It also exposes <a href=&quot;#G&quot;>.child_g.G</a>. These links should all point to the local instance:</p>
 
 <ul>
-<li><a href=&quot;#G&quot;>G</a></li>
-<li><a href=&quot;#G&quot;>G</a></li>
-<li><a href=&quot;#G&quot;>G</a></li>
+<li><a href=&quot;#G&quot;>demopackage.G</a></li>
+<li><a href=&quot;#G&quot;>demopackage.subpackage.G</a></li>
+<li><a href=&quot;#G&quot;>demopackage.subpackage.child_g.G</a></li>
 </ul>
 </div>
 
@@ -1699,8 +1699,8 @@ <h1 class=&quot;modulename&quot;>
 
 <ul>
 <li><a href=&quot;../demopackage.html#G&quot;>demopackage.G</a></li>
-<li><a href=&quot;../demopackage.html#G&quot;>demopackage.G</a></li>
-<li><a href=&quot;../demopackage.html#G&quot;>demopackage.G</a></li>
+<li><a href=&quot;../demopackage.html#G&quot;>demopackage.subpackage.G</a></li>
+<li><a href=&quot;../demopackage.html#G&quot;>demopackage.subpackage.child_g.G</a></li>
 </ul>
 </div>
 
@@ -2044,7 +2044,7 @@ <h1 class=&quot;modulename&quot;>
 </span></pre></div>
 
 
-            <div class=&quot;docstring&quot;><p>This class is defined in <a href=&quot;&quot;>demopackage.child_c</a> and inherits from <a href=&quot;../demopackage.html#B&quot;>demopackage.B</a>.</p>
+            <div class=&quot;docstring&quot;><p>This class is defined in <a href=&quot;&quot;>demopackage.child_c</a> and inherits from <a href=&quot;../demopackage.html#B&quot;>.child_b.B</a>.</p>
 </div>
 
 

test/testdata/top_level_reimports.html

@@ -63,10 +63,10 @@ <h1 class="modulename">
                         <div class="docstring"><p>Test that objects re-exposed from an internal module are properly interlinked if they appear on the same page.</p>
 
 <ul>
-<li><a href="#baz">baz</a></li>
-<li><a href="#baz">baz()</a></li>
-<li><code><a href="#baz">baz</a></code></li>
-<li><code><a href="#baz">baz()</a></code></li>
+<li><a href="#baz">top_level_reimports._internal.baz</a></li>
+<li><a href="#baz">top_level_reimports._internal.baz()</a></li>
+<li><code><a href="#baz">top_level_reimports._internal.baz</a></code></li>
+<li><code><a href="#baz">top_level_reimports._internal.baz()</a></code></li>
 </ul>
 </div>