📚 DOCS: Add live preview (w/ pyscript) (#679)

docs/_static/custom.css

@@ -22,3 +22,31 @@ h3::before {
 .admonition > .admonition-title, div.admonition.no-icon > .admonition-title {
     padding-left: .6rem;
 }
+
+/* Live preview page */
+iframe.pyscript, textarea.pyscript {
+    width: 100%;
+    height: 400px;
+}
+iframe.pyscript {
+    padding: 4px;
+}
+textarea.pyscript {
+    padding: 30px 20px 20px;
+    border-radius: 8px;
+    resize: vertical;
+    font-size: 16px;
+    font-family: monospace;
+}
+.display-flex {
+    display: flex;
+}
+.display-inline-block {
+    display: inline-block;
+    margin-right: 1rem;
+    margin-bottom: 0;
+}
+span.label {
+    /* pyscript changes this and it messes up footnote labels */
+    all: unset;
+}

docs/conf.py

@@ -35,6 +35,7 @@
     "sphinxext.rediraffe",
     "sphinxcontrib.mermaid",
     "sphinxext.opengraph",
+    "sphinx_pyscript",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.md

@@ -30,14 +30,24 @@ sd_hide_title: true
 A Sphinx and Docutils extension to parse MyST,
 a rich and extensible flavour of Markdown for authoring technical and scientific documentation.
 
+````{div} sd-d-flex-row
 ```{button-ref} intro
 :ref-type: doc
 :color: primary
-:class: sd-rounded-pill
+:class: sd-rounded-pill sd-mr-3
 
 Get Started
 ```
 
+```{button-ref} live-preview
+:ref-type: doc
+:color: secondary
+:class: sd-rounded-pill
+
+Live Demo
+```
+````
+
 :::
 
 ::::
@@ -115,6 +125,7 @@ The MyST markdown language and MyST parser are both supported by the open commun
 ```{toctree}
 :hidden:
 intro.md
+live-preview.md
 ```
 
 ```{toctree}

docs/live-preview.md

@@ -0,0 +1,110 @@
+---
+py-config:
+  splashscreen:
+    autoclose: true
+  packages:
+    - myst-docutils
+    - docutils==0.19
+    - pygments
+---
+
+# Live Preview
+
+This is a live preview of the MyST Markdown [docutils renderer](docutils.md).
+You can edit the text/configuration below and see the live output.[^note]
+
+[^note]: Additional styling is usually provided by Sphinx themes.
+
+```{py-script}
+:file: live_preview.py
+```
+
+::::::::{grid} 1 1 1 2
+
+:::::::{grid-item}
+:child-align: end
+
+```{raw} html
+<div><u><span id="myst-version"></span></u></div>
+```
+
+:::::{tab-set}
+::::{tab-item} Input text
+````{raw} html
+<textarea class="pyscript" id="input_myst">
+# Heading 1
+
+Hallo world!
+
+```{note}
+An admonition note!
+```
+
+term
+: definition
+
+$$\pi = 3.14159$$
+
+```{list-table}
+:header-rows: 1
+:align: center
+
+* - Header 1
+  - Header 2
+* - Item 1
+  - Item 2
+```
+
+```{figure} https://via.placeholder.com/150
+:width: 100px
+:align: center
+
+Figure caption
+```
+</textarea>
+````
+
+::::
+::::{tab-item} Configuration (YAML)
+<textarea class="pyscript" id="input_config">
+# see: https://docutils.sourceforge.io/docs/user/config.html
+myst_enable_extensions:
+- colon_fence
+- deflist
+- dollarmath
+myst_highlight_code_blocks: false
+embed_stylesheet: true
+stylesheet_path:
+- minimal.css
+</textarea>
+::::
+:::::
+
+:::::::
+:::::::{grid-item}
+:child-align: end
+
+```{raw} html
+<div class="display-flex">
+<label for="output_format" class="display-inline-block">Output Format:</label>
+<select id="output_format" class="display-inline-block">
+  <option value="pseudoxml">AST</option>
+  <option value="html5" selected>HTML</option>
+  <option value="latex">LaTeX</option>
+</select>
+</div>
+```
+
+::::{tab-set}
+:::{tab-item} HTML Render
+<iframe class="pyscript" id="output_html" readonly="true"></iframe>
+:::
+:::{tab-item} Raw Output
+<textarea class="pyscript" id="output_raw" readonly="true"></textarea>
+:::
+:::{tab-item} Warnings
+<textarea class="pyscript" id="output_warnings" readonly="true"></textarea>
+:::
+::::
+:::::::
+::::::::

docs/live_preview.py

@@ -0,0 +1,63 @@
+from io import StringIO
+
+import yaml
+from docutils.core import publish_string
+from js import document
+
+from myst_parser import __version__
+from myst_parser.parsers.docutils_ import Parser
+
+
+def convert(input_config: str, input_myst: str, writer_name: str) -> dict:
+    warning_stream = StringIO()
+    try:
+        settings = yaml.safe_load(input_config) if input_config else {}
+        assert isinstance(settings, dict), "not a dictionary"
+    except Exception as exc:
+        warning_stream.write(f"ERROR: config load: {exc}\n")
+        settings = {}
+    settings.update(
+        {
+            "output_encoding": "unicode",
+            "warning_stream": warning_stream,
+        }
+    )
+    try:
+        output = publish_string(
+            input_myst,
+            parser=Parser(),
+            writer_name=writer_name,
+            settings_overrides=settings,
+        )
+    except Exception as exc:
+        output = f"ERROR: conversion:\n{exc}"
+    return {"output": output, "warnings": warning_stream.getvalue()}
+
+
+version_label = document.querySelector("span#myst-version")
+config_textarea = document.querySelector("textarea#input_config")
+input_textarea = document.querySelector("textarea#input_myst")
+output_iframe = document.querySelector("iframe#output_html")
+output_raw = document.querySelector("textarea#output_raw")
+warnings_textarea = document.querySelector("textarea#output_warnings")
+oformat_select = document.querySelector("select#output_format")
+
+
+def do_convert(event=None):
+    result = convert(config_textarea.value, input_textarea.value, oformat_select.value)
+    output_raw.value = result["output"]
+    if "html" in oformat_select.value:
+        output_iframe.contentDocument.body.innerHTML = result["output"]
+    else:
+        output_iframe.contentDocument.body.innerHTML = (
+            "Change output format to HTML to see output"
+        )
+    warnings_textarea.value = result["warnings"]
+
+
+version_label.textContent = f"myst-parser v{__version__}"
+config_textarea.oninput = do_convert
+input_textarea.oninput = do_convert
+oformat_select.onchange = do_convert
+
+do_convert()

pyproject.toml

@@ -55,11 +55,12 @@ linkify = ["linkify-it-py~=1.0"]
 rtd = [
     "ipython",
     # currently required to get sphinx v5
-    "sphinx-book-theme @ git+https://github.com/executablebooks/sphinx-book-theme.git@8da268fce3159755041e8db93e132221a0b0def5#egg=sphinx-book-theme",
+    "sphinx-book-theme==0.4.0rc1",
     "sphinx-design",
     "sphinxext-rediraffe~=0.2.7",
     "sphinxcontrib.mermaid~=0.7.1",
     "sphinxext-opengraph~=0.6.3",
+    "sphinx-pyscript",
 ]
 testing = [
     "beautifulsoup4",