starting to generate HTML for examples

Author: gvwilson

docs/bin/example_pages.py

@@ -2,12 +2,15 @@
 
 import argparse
 import frontmatter
+from html import escape
+from markdown import markdown
 from pathlib import Path
 import re
 
 from utils import _log, _str
 
 
+HTML_TAG_RE = re.compile(r'<[^>]*>')
 SUITE_RE = re.compile(r'where:"suite","(.+?)"')
 
 
@@ -41,6 +44,77 @@ def _get_suite(path, content):
     return m.group(1)
 
 
+def _make_html(examples):
+    """Build HTML page full of examples."""
+    accum = []
+    for counter, (path, record) in enumerate(examples):
+        header = record["header"]
+        content = record["content"]
+        accum.append('<div class="section">\n')
+        accum.append('  <div class="row auto-eg-padding">\n')
+
+        accum.append(_make_html_name(path, header))
+
+        accum.append('  <div class="row">\n')
+        accum.append(_make_html_text(path, header, content))
+        accum.append('  </div>\n')
+
+        accum.append('    </div>\n')
+        accum.append('</div>\n\n')
+
+    return "".join(accum)
+
+
+HTML_NAME = """\
+    <div class=" row twelve columns">
+      <h3 id="{name}">
+        <a class="no_underline plot-blue" href="#{name}">{name}</a>
+      </h3>
+    </div>
+"""
+
+def _make_html_name(path, header):
+    """Make example name block."""
+    name = header["name"] if header["name"] else ""
+    _log(not name, f"{path} does not have name")
+    name = _strip_html(name.replace(" ", "-").replace(",", "").lower())
+    return HTML_NAME.format(name=name)
+
+HTML_TEXT = """\
+  <div class="{columns} columns">
+    {markdown_content}
+    {page_content}
+    {description}
+  </div>
+"""
+
+HTML_TEXT_PAGE_CONTENT = """\
+      <div class="z-depth-1">
+        <pre><code class="javascript">{text}</code></pre>
+      </div>
+"""
+
+HTML_TEXT_DESCRIPTION = """\
+      <blockquote>
+        {text}
+      </blockquote>
+"""
+
+def _make_html_text(path, header, content):
+    """Make text of example."""
+    columns = "twelve" if "horizontal" in header.get("arrangement", "") else "six"
+    markdown_content = markdown(header.get("markdown_content", ""))
+    page_content = HTML_TEXT_PAGE_CONTENT.format(text=escape(content)) if content else ""
+    description = header.get("description", "")
+    description = HTML_TEXT_DESCRIPTION.format(text=description) if description else ""
+    return HTML_TEXT.format(
+        columns=columns,
+        markdown_content=markdown_content,
+        page_content=page_content,
+        description=description,
+    )
+
+
 def _parse_args():
     """Parse command-line arguments."""
     parser = argparse.ArgumentParser(description="Generate HTML example documentation")
@@ -56,18 +130,25 @@ def _process(args, path, record, example_files):
     if (suite := _get_suite(path, record["content"])) is None:
         return
 
-    children = [
-        p for p, r in example_files.items()
+    examples = [
+        (p, r) for p, r in example_files.items()
         if r["header"].get("suite", None) == suite
     ]
-    children.sort(key=lambda p: (example_files[p]["header"]["order"], str(p)))
+    examples.sort(key=lambda pair: (example_files[pair[0]]["header"]["order"], str(pair[0])))
 
     section = record["header"]["permalink"].strip("/").split("/")[-1]
-    _log(args.verbose > 0, f"...{section}: {len(children)}")
+    _log(args.verbose > 0, f"...{section}: {len(examples)}")
+
+    html = _make_html(examples)
 
     output_path = args.outdir / section / "index.html"
     output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(record["header"]["name"])
+    output_path.write_text(html)
+
+
+def _strip_html(text):
+    """Remove HTML tags from text."""
+    return HTML_TAG_RE.sub("", text)
 
 
 if __name__ == "__main__":

pyproject.toml

@@ -4,5 +4,6 @@ description = "Plotly JavaScript charting library"
 version = "3.1.0"
 requires-python = ">=3.12"
 dependencies = [
+    "markdown",
     "python-frontmatter"
 ]