ENH: Support configurable markdown extensions (CLI-only)

Author: kernc

pdoc/cli.py

@@ -557,6 +557,18 @@ def docfilter(obj, _filters=args.filter.strip().split(',')):
                for module in args.modules]
     pdoc.link_inheritance()
 
+    # Loading is done. Output stage ...
+    config = pdoc._get_config(**template_config)
+
+    # Load configured global markdown extensions
+    # XXX: This is hereby enabled only for CLI usage as for
+    #  API use I couldn't figure out where reliably to put it.
+    if config.get('md_extensions'):
+        from .html_helpers import _md
+        _kwargs = {'extensions': [], 'configs': {}}
+        _kwargs.update(config.get('md_extensions', {}))
+        _md.registerExtensions(**_kwargs)
+
     if args.pdf:
         _print_pdf(modules, **template_config)
         import textwrap
@@ -603,7 +615,7 @@ def docfilter(obj, _filters=args.filter.strip().split(',')):
             sys.stdout.write(os.linesep * (1 + 2 * int(module != modules[-1])))
 
     if args.html:
-        lunr_config = pdoc._get_config(**template_config).get('lunr_search')
+        lunr_config = config.get('lunr_search')
         if lunr_config is not None:
             _generate_lunr_search(
                 modules, lunr_config.get("index_docstrings", True), template_config)

pdoc/html_helpers.py

@@ -73,12 +73,12 @@ def glimpse(text: str, max_length=153, *, paragraph=True,
     output_format='html5',    # type: ignore[arg-type]
     extensions=[
         "markdown.extensions.abbr",
+        "markdown.extensions.admonition",
         "markdown.extensions.attr_list",
         "markdown.extensions.def_list",
         "markdown.extensions.fenced_code",
         "markdown.extensions.footnotes",
         "markdown.extensions.tables",
-        "markdown.extensions.admonition",
         "markdown.extensions.smarty",
         "markdown.extensions.toc",
     ],

pdoc/templates/config.mako

@@ -61,4 +61,10 @@
     # Note: in Python docstrings, either all backslashes need to be escaped (\\)
     # or you need to use raw r-strings.
     latex_math = False
+
+    # Additional markdown extensions to enable. See:
+    # https://python-markdown.github.io/extensions/
+    # https://python-markdown.github.io/reference/#extensions
+    # https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
+    md_extensions = {'extensions': [], 'configs': {}}
 %>

pdoc/test/__init__.py

@@ -18,6 +18,7 @@
 from glob import glob
 from io import StringIO
 from itertools import chain
+from pathlib import Path
 from random import randint
 from tempfile import TemporaryDirectory
 from time import sleep
@@ -477,6 +478,15 @@ def test_resolve_typing_forwardrefs(self):
             out = out.getvalue()
             self.assertIn('Set[Bar]', out)
 
+    def test_md_extensions(self):
+        with temp_dir() as path, chdir(path):
+            Path('foo.py').write_text('"""secret: meta data\n\nOnly this comment expected."""')
+            with redirect_streams() as (stdout, _), \
+                    run_html('foo.py',
+                             config="md_extensions={'extensions': ['markdown.extensions.meta']}",):
+                self._check_files(include_patterns=['<p>Only this comment expected.</p>'],
+                                  exclude_patterns=['<p>secret: meta data</p>'])
+
 
 class ApiTest(unittest.TestCase):
     """