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,110 @@
+"""Rebuild a reference page from the Jekyll HTML and plot schema JSON file."""
+
+import argparse
+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"),
+)
+
+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 _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):
+    """Generate HTML documentation for a trace's attributes."""
+
+
+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
+
+
+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 = []