auto-link URLs, refs #401 (#402)

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,27 @@
 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 +166,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(  # type: ignore
+        docstring,
+        extras=markdown_extensions,
+        link_patterns=markdown_link_patterns,
+    )
 
 
 @pass_context

test/test_doc_pyi.py

@@ -27,6 +27,10 @@ class foo_cls:
 
 
 def test_invalid_stub_file(monkeypatch):
-    monkeypatch.setattr(doc_pyi, "find_stub_file", lambda m: here / "import_err/err/__init__.py")
-    with pytest.warns(UserWarning, match=r"Error parsing type stubs[\s\S]+RuntimeError"):
+    monkeypatch.setattr(
+        doc_pyi, "find_stub_file", lambda m: here / "import_err/err/__init__.py"
+    )
+    with pytest.warns(
+        UserWarning, match=r"Error parsing type stubs[\s\S]+RuntimeError"
+    ):
         _ = doc.Module(doc).members

test/test_extract.py

@@ -10,16 +10,13 @@
 
 def test_walk_specs():
     assert walk_specs(["dataclasses"]) == ["dataclasses"]
-    assert (
-        walk_specs(
-            [
-                here / "testdata" / "demopackage",
-                "!demopackage",
-                "demopackage.child_b",
-            ]
-        )
-        == ["demopackage.child_b"]
-    )
+    assert walk_specs(
+        [
+            here / "testdata" / "demopackage",
+            "!demopackage",
+            "demopackage.child_b",
+        ]
+    ) == ["demopackage.child_b"]
 
     assert walk_specs(["demopackage", "!demopackage.child_excluded"]) == [
         "demopackage",

test/test_render_helpers.py

@@ -98,3 +98,40 @@ 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>