auto-link URLs, refs mitmproxy#401

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 # Unreleased: pdoc next
 
+ - Extend auto-linking of URLs in Markdown.
+   ([#401](https://github.com/mitmproxy/pdoc/issues/401), [@mhils](https://github.com/mhils))
+
 # 2022-06-03: pdoc 12.0.1
 
  - Fix linking of some function return annotations.

pdoc/render_helpers.py

@@ -56,6 +56,7 @@
     "fenced-code-blocks": {"cssclass": formatter.cssclass},
     "footnotes": None,
     "header-ids": None,
+    "link-patterns": None,
     "markdown-in-html": None,
     "pyshell": None,
     "strike": None,
@@ -67,6 +68,24 @@
 The default extensions loaded for `markdown2`.
 Overwrite this to configure Markdown rendering.
 """
+markdown_link_patterns = [(
+    re.compile(
+        r"""
+            \b
+            (
+                (?:https?://|(?<!//)www\.)    # prefix - https:// or www.
+                \w[\w_\-]*(?:\.\w[\w_\-]*)*   # host
+                [^<>\s"']*                    # rest of url
+                (?<![?!.,:*_~);])             # exclude trailing punctuation
+                (?=[?!.,:*_~);]?(?:[<\s]|$))  # make sure that we're not followed by " or ', i.e. we're outside of href="...".
+            )
+        """,
+        re.X
+    ), r"\1"
+)]
+"""
+Link pattern used for markdown2's [`link-patterns` extra](https://github.com/trentm/python-markdown2/wiki/link-patterns).
+"""
 
 
 @cache
@@ -144,7 +163,11 @@ def to_html(docstring: str) -> str:
     # careful: markdown2 returns a subclass of str with an extra
     # .toc_html attribute. don't further process the result,
     # otherwise this attribute will be lost.
-    return pdoc.markdown2.markdown(docstring, extras=markdown_extensions)  # type: ignore
+    return pdoc.markdown2.markdown(
+        docstring,
+        extras=markdown_extensions,
+        link_patterns=markdown_link_patterns,
+    )  # type: ignore
 
 
 @pass_context

test/test_render_helpers.py

@@ -98,3 +98,19 @@ def test_markdown_toc():
     It's easy to introduce a `.strip()` in there and this gets washed away, so let's test that it works properly.
     """
     assert to_html("#foo\n#bar").toc_html  # type: ignore
+
+
+@pytest.mark.parametrize(
+    "md,html",
+    [
+        ("https://example.com/", '<p><a href="https://example.com/">https://example.com/</a></p>\n'),
+        ('<https://example.com>', '<p><a href="https://example.com">https://example.com</a></p>\n'),
+        ('<a href="https://example.com">link</a>', '<p><a href="https://example.com">link</a></p>\n'),
+        ('[link](https://example.com)', '<p><a href="https://example.com">link</a></p>\n'),
+        ('See the [Python home page ](https://www.python.org) for info.', '<p>See the <a href="https://www.python.org">Python home page </a> for info.</p>\n'),
+        ('See https://www.python.org.', '<p>See <a href="https://www.python.org">https://www.python.org</a>.</p>\n'),
+        ('See **https://www.python.org**.', '<p>See <strong>https://www.python.org</strong>.</p>\n'),
+    ]
+)
+def test_markdown_autolink(md, html):
+    assert to_html(md) == html

test/testdata/flavors_google.html

@@ -1632,7 +1632,7 @@ <h6 id="args">Args</h6>
 </span></pre></div>
 
 
-            <div class="docstring"><p>Test case for https://github.com/mitmproxy/pdoc/issues/264.</p>
+            <div class="docstring"><p>Test case for <a href="https://github.com/mitmproxy/pdoc/issues/264">https://github.com/mitmproxy/pdoc/issues/264</a>.</p>
 
 <h6 id="example">Example</h6>
 

test/testdata/misc.html

@@ -1671,7 +1671,7 @@ <h5>Inherited Members</h5>
 </span></pre></div>
 
 
-            <div class="docstring"><p>multi-line decorator, https://github.com/mitmproxy/pdoc/issues/246</p>
+            <div class="docstring"><p>multi-line decorator, <a href="https://github.com/mitmproxy/pdoc/issues/246">https://github.com/mitmproxy/pdoc/issues/246</a></p>
 </div>