starting to build replacement for Jekyll

Author: gvwilson

docs/Makefile

@@ -1,6 +1,7 @@
 # Manage plotly.js documentation.
 
 JEKYLL=bundle exec jekyll
+RUN = uv run
 SCHEMA_SRC=../test/plot-schema.json
 SCHEMA_DST=_data/plotschema.json
 
@@ -14,6 +15,11 @@ build:
 	cp ${SCHEMA_SRC} ${SCHEMA_DST}
 	${JEKYLL} build
 
+## reference: build reference documentation in ./tmp
+reference:
+	@mkdir -p tmp
+	${RUN} bin/make_reference_pages.py --schema ${SCHEMA_SRC} --outdir tmp _posts/reference_pages/javascript/2020-07-20-bar.html
+
 ## serve: display documentation
 serve:
 	@mkdir -p _data

docs/bin/make_reference_pages.py

@@ -0,0 +1,221 @@
+"""Rebuild a reference page from the Jekyll HTML and plot schema JSON file."""
+
+import argparse
+from html import escape
+import json
+from pathlib import Path
+import re
+import sys
+
+
+INCLUDE_RE = re.compile(
+    r'\{%\s*include\s+posts/reference-trace.html\s+trace_name="(.+?)"\s+trace_data=site\.data\.plotschema\.traces\.(.+?)\s*%}'
+)
+TITLE_RE = re.compile(r"<h2>.+?<code>(.+?)</code>.+?</h2>")
+
+
+PLOT_SCHEMA_CONTENT = """\
+<div class="description">
+  A <code>{trace_name}</code> trace is an object with the key <code>"type"</code> equal to <code>"{trace_data_attributes_type}"</code>
+  (i.e. <code>{{"type": "{trace_data_attributes_type}"}}</code>) and any of the keys listed below.
+  <br><br>{trace_data_meta_description}<br><br>
+</div>
+"""
+
+PLOT_SCHEMA_REPLACEMENTS = (
+    ('*', '"'),
+    ("{array}", "array"),
+    ("{arrays}", "arrays"),
+    ("{object}", "object"),
+    ("{2D array}", "2D array"),
+)
+
+OBJ_EXCLUDES = {
+    "_arrayAttrRegexps",
+    "_deprecated",
+    "_isLinkedToArray",
+    "_isSubplotObj",
+    "description",
+    "editType",
+    "extras",
+    "flags",
+    "impliedEdits",
+    "items",
+    "magic_underscores",
+    "role",
+    "stream",
+    "transforms"
+    "uid",
+}
+
+SKIP_MUSTMATCH = {
+    "annotations",
+    "coloraxis",
+    "geo",
+    "images",
+    "mapbox",
+    "polar",
+    "scene",
+    "shapes",
+    "sliders",
+    "smith",
+    "ternary",
+    "updatemenus",
+    "xaxis",
+    "yaxis",
+}
+
+
+def main():
+    """Main driver."""
+    args = _parse_args()
+    args.outdir.mkdir(parents=True, exist_ok=True)
+
+    schema = json.loads(args.schema.read_text())
+    assert "traces" in schema, f"'traces' missing from {args.schema}"
+
+    for src_path in args.inputs:
+        _log(args.verbose > 0, f"...{src_path}")
+        src_content = src_path.read_text()
+
+        m = TITLE_RE.search(src_content)
+        if _log(not m, f"failed to match title in {src_path}"):
+            continue
+        title = m.group(1)
+
+        m = INCLUDE_RE.search(src_content)
+        if _log(not m, f"failed to match include in {src_path}"):
+            continue
+        if _log(m.group(1) != title, f"title {title} != include title {m.group(1)} in {src_path}"):
+            continue
+        trace_name = m.group(2)
+        trace_data = schema["traces"].get(trace_name, None)
+        if _log(trace_data is None, f"trace '{trace_name}' not found in {args.schema}"):
+            continue
+
+        html = _reference_trace(args, schema, trace_name, trace_data)
+        print(html)
+
+
+def _get_field(value, key, default=None):
+    """Simulate Jekyll's obj.field (which is 'nil' if 'obj' is a string)."""
+    if isinstance(value, str):
+        return default
+    assert isinstance(value, dict), f"{value} not recognized"
+    return value.get(key, default)
+
+
+def _log(condition, msg):
+    """Conditionally report progress."""
+    if condition:
+        print(msg, file=sys.stderr)
+    return condition
+
+
+def _parse_args():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(description="Generate HTML reference documentation")
+    parser.add_argument("inputs", nargs="+", type=Path, help="Input Jekyll files")
+    parser.add_argument("--schema", type=Path, help="Path to plot schema JSON file")
+    parser.add_argument("--outdir", type=Path, help="Output directory")
+    parser.add_argument("--verbose", type=int, default=0, help="Integer verbosity level")
+    return parser.parse_args()
+
+
+def _reference_block(args, accum, attributes, parent_link, parent_path, block, mustmatch=None):
+    """Generate HTML documentation for a trace's attributes."""
+    accum.append("<ul>")
+    for key, value in attributes.items():
+        last_three = key[-3:]
+        if (last_three == "src") or (key in OBJ_EXCLUDES):
+            continue
+        if _skip_mustmatch(key, mustmatch):
+            continue
+        accum.append("<li>")
+
+        id = f"{parent_link}-{key}"
+        accum.append(f'<a class="attribute-name" id="{id}" href="#{id}">')
+        accum.append(f"    {key}")
+        accum.append("</a>")
+
+        accum.append(f"<br><em>Parent:</em> <code>{parent_path.replace('-', '.')}</code>")
+
+        if (key == "type") and (block == "data"):
+            accum.append("<br />")
+            accum.append(f"<em>Type:</em> *{value}*")
+
+        if _get_field(value, "valType"):
+            _reference_block_valtype(accum, value)
+
+        if _get_field(value, "dflt"):
+            _reference_block_dflt(accum, value)
+
+        if _get_field(value, "items") and (_get_field(value, "valType") != "info_array"):
+            _reference_block_array(accum, value)
+        elif _get_field(value, "role") == "object":
+            accum.append('<br><em>Type:</em> {{object}} containing one or more of the keys listed below.')
+
+        if _get_field(value, "description", "") != "":
+            accum.append(f"<p>{escape(value.get('description'))}</p>")
+
+        if _get_field(value, "role") == "object":
+            _reference_block_object(accum, value)
+
+        accum.append("</li>")
+    accum.append("</ul>")
+
+
+def _reference_block_valtype(accum, value):
+    """Handle a value type."""
+
+
+def _reference_block_dflt(accum, value):
+    """Handle a default."""
+
+
+def _reference_block_array(accum, value):
+    """Handle an array."""
+
+
+def _reference_block_object(accum, value):
+    """Handle an object."""
+
+
+def _reference_trace(args, schema, trace_name, trace_data):
+    """Generate HTML documentation for a trace."""
+    plot_schema_content = PLOT_SCHEMA_CONTENT.format(
+        trace_name=trace_name,
+        trace_data_attributes_type=trace_data["attributes"]["type"],
+        trace_data_meta_description=trace_data["meta"]["description"],
+    )
+    plot_schema_content = _replace_special(plot_schema_content)
+    accum = [plot_schema_content]
+
+    parent_link = trace_name
+    parent_path = f"data[type={trace_name}]"
+    attributes = trace_data["attributes"]
+    _reference_block(args, accum, attributes, parent_link, parent_path, "data")
+
+    return "\n".join(accum)
+
+
+def _replace_special(text):
+    """Handle our funky special-case strings."""
+    for original, replacement in PLOT_SCHEMA_REPLACEMENTS:
+        text = text.replace(original, replacement)
+    return text
+
+
+def _skip_mustmatch(key, mustmatch):
+    if mustmatch is None:
+        return False
+    if mustmatch == "global":
+        return key in SKIP_MUSTMATCH
+    elif key != mustmatch:
+        return True
+    else:
+        return False
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,6 @@
+[project]
+name = "plotly.js"
+description = "Plotly JavaScript charting library"
+version = "3.1.0"
+requires-python = ">=3.12"
+dependencies = []