🔧 Add myst-docutils-demo CLI

myst_parser/parsers/docutils_.py

@@ -15,8 +15,10 @@
 
 import yaml
 from docutils import frontend, nodes
-from docutils.core import default_description, publish_cmdline
+from docutils.core import default_description, publish_cmdline, publish_string
+from docutils.frontend import filter_settings_spec
 from docutils.parsers.rst import Parser as RstParser
+from docutils.writers.html5_polyglot import HTMLTranslator, Writer
 
 from myst_parser._compat import Literal, get_args, get_origin
 from myst_parser.config.main import (
@@ -321,6 +323,27 @@ def parse(self, inputstring: str, document: nodes.document) -> None:
         self.finish_parse()
 
 
+class SimpleTranslator(HTMLTranslator):
+    def stylesheet_call(self, *args, **kwargs):
+        return ""
+
+
+class SimpleWriter(Writer):
+
+    settings_spec = filter_settings_spec(
+        Writer.settings_spec,
+        "template",
+    )
+
+    def apply_template(self):
+        subs = self.interpolation_dict()
+        return "%(body)s\n" % subs
+
+    def __init__(self):
+        self.parts = {}
+        self.translator_class = SimpleTranslator
+
+
 def _run_cli(writer_name: str, writer_description: str, argv: Optional[List[str]]):
     """Run the command line interface for a particular writer."""
     publish_cmdline(
@@ -343,6 +366,44 @@ def cli_html5(argv: Optional[List[str]] = None):
     _run_cli("html5", "HTML5 documents", argv)
 
 
+def cli_html5_demo(argv: Optional[List[str]] = None):
+    """Cmdline entrypoint for converting MyST to simple HTML5 demonstrations.
+
+    This is a special case of the HTML5 writer,
+    that only outputs the body of the document.
+    """
+    publish_cmdline(
+        parser=Parser(),
+        writer=SimpleWriter(),
+        description=(
+            f"Generates body HTML5 from standalone MyST sources.\n{default_description}"
+        ),
+        settings_overrides={
+            "doctitle_xform": False,
+            "sectsubtitle_xform": False,
+            "initial_header_level": 1,
+        },
+        argv=argv,
+    )
+
+
+def to_html5_demo(inputstring: str, **kwargs) -> str:
+    """Convert a MyST string to HTML5."""
+    overrides = {
+        "doctitle_xform": False,
+        "sectsubtitle_xform": False,
+        "initial_header_level": 1,
+        "output_encoding": "unicode",
+    }
+    overrides.update(kwargs)
+    return publish_string(
+        inputstring,
+        parser=Parser(),
+        writer=SimpleWriter(),
+        settings_overrides=overrides,
+    )
+
+
 def cli_latex(argv: Optional[List[str]] = None):
     """Cmdline entrypoint for converting MyST to LaTeX."""
     _run_cli("latex", "LaTeX documents", argv)

tests/test_docutils.py

@@ -12,9 +12,11 @@
     attr_to_optparse_option,
     cli_html,
     cli_html5,
+    cli_html5_demo,
     cli_latex,
     cli_pseudoxml,
     cli_xml,
+    to_html5_demo,
 )
 
 
@@ -54,6 +56,18 @@ def test_cli_html5(monkeypatch, capsys):
     assert "text" in captured.out
 
 
+def test_cli_html5_demo(monkeypatch, capsys):
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"text")))
+    cli_html5_demo([])
+    captured = capsys.readouterr()
+    assert not captured.err
+    assert "text" in captured.out
+
+
+def test_to_html5_demo():
+    assert to_html5_demo("text").strip() == "<p>text</p>"
+
+
 def test_cli_latex(monkeypatch, capsys):
     monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"text")))
     cli_latex([])