Support embedding local images (#460)

* support embedding local images

* [autofix.ci] apply automated fixes

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: mhils

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased: pdoc next
 
+ - Docstrings can now include local images which will be embedded into the page, e.g. `![image](./image.png)`.
+   ([#282](https://github.com/mitmproxy/pdoc/issues/282), @mhils)
  - Fix a bug in parsing Google-style docstrings with extraneous whitespace.
    ([#459](https://github.com/mitmproxy/pdoc/pull/459), @vsajip, @mhils)
  - `pdoc.doc.Doc.members` now includes variables without type annotation and docstring.

docs/logo.png

@@ -12,7 +12,10 @@
 """
 from __future__ import annotations
 
+import base64
 import inspect
+import mimetypes
+import os
 import re
 import warnings
 from pathlib import Path
@@ -38,9 +41,32 @@ def convert(docstring: str, docformat: str, source_file: Path | None) -> str:
     if "numpy" in docformat:
         docstring = numpy(docstring)
 
+    if source_file is not None and os.environ.get("PDOC_EMBED_IMAGES") != "0":
+        docstring = embed_images(docstring, source_file)
+
     return docstring
 
 
+def embed_images(docstring: str, source_file: Path) -> str:
+    def embed_local_image(m: re.Match) -> str:
+        image_path = source_file.parent / m["href"]
+        try:
+            image_data = image_path.read_bytes()
+            image_mime = mimetypes.guess_type(image_path)[0]
+        except Exception:
+            return m[0]
+        else:
+            data = base64.b64encode(image_data).decode()
+            return f"![{m['alt']}](data:{image_mime};base64,{data})"
+
+    return re.sub(
+        r"!\[\s*(?P<alt>.*?)\s*]\(\s*(?P<href>.+?)\s*\)",
+        embed_local_image,
+        docstring,
+    )
+    # TODO: Could probably do more here, e.g. support rST or raw HTML replacements.
+
+
 def google(docstring: str) -> str:
     """Convert Google-style docstring sections into Markdown."""
     return re.sub(

pdoc/docstrings.py

@@ -245,6 +245,18 @@ class EnumDemo(enum.Enum):
     BLUE = enum.auto()
 
 
+def embed_image():
+    """
+    This docstring includes an embedded image:
+
+    ```
+    ![pdoc logo](../docs/logo.png)
+    ```
+
+    ![pdoc logo](../../docs/logo.png)
+    """
+
+
 def admonitions():
     """
     pdoc also supports basic reStructuredText admonitions:

test/testdata/demo_long.html

@@ -88,4 +88,5 @@ This …
         <var BLUE = <EnumDemo.BLUE: 3>>
         <var name  # inherited from enum.Enum.name, The name of the Enum…>
         <var value  # inherited from enum.Enum.value, The value of the Enu…>>
+    <function def embed_image(): ...  # This docstring inclu…>
     <function def admonitions(): ...  # pdoc also supports b…>>