feat: building example pages

Author: gvwilson

.gitignore

@@ -1,6 +1,8 @@
 node_modules
 _site
 
+__pycache__
+
 build/*
 !build/plotcss.js
 !build/README.md

docs/Makefile

@@ -15,11 +15,17 @@ build:
 	cp ${SCHEMA_SRC} ${SCHEMA_DST}
 	${JEKYLL} build
 
+## examples: build example documentation in ./tmp
+examples:
+	@rm -rf tmp
+	@mkdir -p tmp
+	${RUN} bin/example_pages.py --indir _posts/plotly_js --outdir tmp/javascript --verbose 1
+
 ## reference: build reference documentation in ./tmp
 reference:
 	@rm -rf tmp
 	@mkdir -p tmp
-	${RUN} bin/make_reference_pages.py --schema ${SCHEMA_SRC} --outdir tmp _posts/reference_pages/javascript/*.html
+	${RUN} bin/reference_pages.py --schema ${SCHEMA_SRC} --outdir tmp/reference _posts/reference_pages/javascript/*.html
 
 ## serve: display documentation
 serve:

docs/_posts/reference_pages/javascript/2020-07-20-heatmapgl.html

@@ -0,0 +1,74 @@
+"""Rebuild plotly.js example pages from Jekyll HTML."""
+
+import argparse
+import frontmatter
+from pathlib import Path
+import re
+
+from utils import _log, _str
+
+
+SUITE_RE = re.compile(r'where:"suite","(.+?)"')
+
+
+def main():
+    """Main driver."""
+    args = _parse_args()
+    index_files, example_files = _get_source_files(args)
+    for path, record in index_files.items():
+        _process(args, path, record, example_files)
+
+
+def _get_source_files(args):
+    """Load and classify source files."""
+    index_files = {}
+    example_files = {}
+    for filepath in args.indir.glob("**/*.html"):
+        page = frontmatter.load(filepath)
+        record = {"header": page.metadata, "content": page.content}
+        if not str(filepath).endswith("index.html"):
+            example_files[filepath] = record
+        elif "posts/auto_examples.html" in page.content:
+            index_files[filepath] = record
+    return index_files, example_files
+
+
+def _get_suite(path, content):
+    """Get suite specification from index file."""
+    m = SUITE_RE.search(content)
+    if _log(not m, f"cannot find 'suite' in index file {path}"):
+        return None
+    return m.group(1)
+
+
+def _parse_args():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(description="Generate HTML example documentation")
+    parser.add_argument("--indir", type=Path, help="Input directory")
+    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 _process(args, path, record, example_files):
+    """Process a section."""
+    if (suite := _get_suite(path, record["content"])) is None:
+        return
+
+    children = [
+        p 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)))
+
+    section = record["header"]["permalink"].strip("/").split("/")[-1]
+    _log(args.verbose > 0, f"...{section}: {len(children)}")
+
+    output_path = args.outdir / section / "index.html"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(record["header"]["name"])
+
+
+if __name__ == "__main__":
+    main()

docs/_posts/reference_pages/javascript/2020-07-20-pointcloud.html

@@ -7,6 +7,8 @@
 import re
 import sys
 
+from utils import _log, _str
+
 
 INCLUDE_BLOCK_RE = re.compile(
     r'{%\s*include\s+posts/reference-block.html\s+parentlink="(.+?)"\s+block="(.+?)"\s+parentpath="(.+?)"\s+mustmatch="(.+?)"\s*%}'
@@ -114,7 +116,7 @@ def main():
             _log(not m, f"failed to match include in {src_path}")
             continue
 
-        output_path = args.outdir / "reference" / title.replace(".", "/") / "index.html"
+        output_path = args.outdir / title.replace(".", "/") / "index.html"
         output_path.parent.mkdir(parents=True, exist_ok=True)
         output_path.write_text(html)
 
@@ -140,13 +142,6 @@ def _get(value, key, default=None):
     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")
@@ -237,7 +232,7 @@ def _reference_block_valtype(src_path, accum, key, value):
         accum.append(f"{inner}<em>Type:</em> {_get(value, 'valType')} string.\n\n")
         flags = _get(value, "flags")
         if not flags:
-            print(f"no flags for flaglist in {src_path}", file=sys.stderr)
+            print(f"no flags for flaglist {key} in {src_path}", file=sys.stderr)
             return
 
         accum.append(f"{inner}Any combination of ")

docs/bin/example_pages.py

@@ -0,0 +1,21 @@
+"""Documentation generation utilities."""
+
+import sys
+
+
+def _log(condition, msg):
+    """Conditionally report progress."""
+    if condition:
+        print(msg, file=sys.stderr)
+    return condition
+
+
+def _str(val):
+    """Hacky string conversion."""
+    if isinstance(val, str):
+        return val
+    if isinstance(val, bool):
+        return str(val).lower()
+    if isinstance(val, int):
+        return str(val)
+    return str(val)

docs/bin/make_reference_pages.py renamed to docs/bin/reference_pages.py

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