diff --git a/muppet/format.py b/muppet/format.py index 67aa5550530f35ed799c4dc049c11c9607583718..97c38d1dae3a0c1f3422b7dd3bc535828abe431d 100644 --- a/muppet/format.py +++ b/muppet/format.py @@ -6,7 +6,7 @@ provided as the first element. This program goes through every definition in it, and outputs a complete index.html. """ -from commonmark import commonmark +from .markdown import markdown from subprocess import CalledProcessError import html import sys @@ -1067,13 +1067,13 @@ def print_docstring(name: str, docstring: dict[str, Any]) -> str: # if text := t.get('text'): # text = re.sub(r'(NOTE|TODO)', # r'<mark>\1</mark>', - # commonmark(text)) + # markdown(text)) # out += f"<dd>{text}</dd>" # out += '</dl>' if 'text' in docstring: out += '<div>' - out += commonmark(docstring['text']) + out += markdown(docstring['text']) out += '</div>' return out @@ -1101,7 +1101,7 @@ def build_param_dict(docstring: dict[str, Any]) -> dict[str, str]: if text := t.get('text'): obj[t['name']] = re.sub(r'(NOTE|TODO)', r'<mark>\1</mark>', - commonmark(text)) + markdown(text)) return obj else: return {} diff --git a/muppet/markdown.py b/muppet/markdown.py new file mode 100644 index 0000000000000000000000000000000000000000..df54feebc89f4a18c504dd2ee13f76b457681704 --- /dev/null +++ b/muppet/markdown.py @@ -0,0 +1,49 @@ +""" +Muppet central markdown module. + +This module exports one procedure, ``markdown``. This to easily +configure all markdown rendering to be the same in one central place, +and to allow "easy" switching of the markdown engine. +""" + +from markdown_it import MarkdownIt +from mdit_py_plugins.anchors import anchors_plugin + + +def markdown(text: str) -> str: + """ + Render the given markdown string to HTML. + + The current implementations sets these options and plugins: + + html + Enable HTML in the source, which will be passed verbatim + + linkify + Things which looks like links will be hyperlinked + + anchors_plugin + Each header will get an appropriate id-attribute set, allowing + hyperlinks to it. + + table + Allow markdown tables. + + strikethrough + Allow GFM-like strikethrough (``~~striken out~~``). + + :param text: + A Markdown string. + + :returns: + A HTML string. + """ + md = MarkdownIt('commonmark', {'html': True, 'linkify': True}) \ + .use(anchors_plugin) \ + .enable('table') \ + .enable('strikethrough') + + return md.render(text) + + +# header_text.downcase().replace(' ', '-') diff --git a/muppet/output.py b/muppet/output.py index 242b3b59d44b9a7f72054f43d12919c674fab7a1..0e83c5848148f3531815c03a1e9534cd9b32e8c5 100644 --- a/muppet/output.py +++ b/muppet/output.py @@ -14,7 +14,7 @@ from jinja2 import ( FileSystemLoader, ) from .lookup import lookup, Ref -from commonmark import commonmark +from .markdown import markdown from .format import ( format_class, format_type_alias, @@ -103,7 +103,7 @@ def index_item(obj: dict) -> IndexItem: } if summary: - out['summary'] = commonmark(summary) + out['summary'] = markdown(summary) return out @@ -356,7 +356,7 @@ def setup_module(base: str, module: ModuleEntry, *, path_base: str) -> None: pathlib.Path(os.path.join(path, name)).mkdir(exist_ok=True) out_path = os.path.join(path, name, 'index.html') - content = commonmark(raw_content) + content = markdown(raw_content) template = jinja.get_template('content.html') crumbs = breadcrumbs(('Environment', ''), module.name, diff --git a/setup.cfg b/setup.cfg index 9192ddad3e6333d84aa08fed467106343edce221..8d2416dbfee8285f4256e3d5444ab8a3caec993c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -29,6 +29,7 @@ packages = muppet python_requires = >= 3.10 install_requires = jinja2~=3.1.2 - commonmark~=0.9.1 + markdown-it-py~=2.2 + mdit_py_plugins=~0.3 setup_requires = setuptools