diff --git a/pdoc/cli.py b/pdoc/cli.py index 85a78ab7..e7acc901 100755 --- a/pdoc/cli.py +++ b/pdoc/cli.py @@ -537,6 +537,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 @@ -583,7 +595,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) diff --git a/pdoc/html_helpers.py b/pdoc/html_helpers.py index 51f7336d..7269845d 100644 --- a/pdoc/html_helpers.py +++ b/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", ], diff --git a/pdoc/templates/config.mako b/pdoc/templates/config.mako index f5e4d476..f077a253 100644 --- a/pdoc/templates/config.mako +++ b/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': {}} %> diff --git a/pdoc/test/__init__.py b/pdoc/test/__init__.py index 0e122a7b..a24eebc4 100644 --- a/pdoc/test/__init__.py +++ b/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 @@ -468,6 +469,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=['

Only this comment expected.

'], + exclude_patterns=['

secret: meta data

']) + class ApiTest(unittest.TestCase): """