feat: use MkDocs to generate documentation from plot-schema.json

1.  Copy `make_ref_pages.py` from graphing-library-docs repository to
    create `bin/make_ref_pages.py` and then refactor to generate
    Markdown stubs for documentation pages.

1.  Write `bin/gen.py` to generate HTML pages from the Markdown stubs
    using the Jinja templates in the `theme` directory for debugging.

1.  Convert Jekyll templates from graphing-library-docs repository to
    Jinja and store in `theme` directory.

1.  Write `requirements.txt` file to install required Python packages.
    -   `beautifulsoup4`: for HTML manipulation
    -   `html5validator`: to validate generated HTML
    -   `jinja2`: for manual template expansion
    -   `mkdocs`: for website generation
    -   `mkdocs-exclude`: to exclude `.jinja` files from generation
    -   `python-frontmatter`: for manual template expansion
    -   `ruff`: for checking `bin` scripts

1.  Write `Makefile` to automate build and test.

1.  Modify documentation comments in some JavaScript files to remove
    stray backticks.

Notes:

1.  As of the time of this commit, the `mkdocs_data_loader` plugin
    must be installed directly from a `.whl` file or similar. It will
    be added to `requirements.txt` once the plugin is on PyPI.

1.  Jinja does not expand directives in Markdown files; it only
    expands those it finds in template `.jinja` files. Because of
    this, the Markdown stubs generated by `bin/make_ref_pages.py` have
    YAML headers but no bodies.

1.  The logic to set the `details` variable in `theme/main.jinja` is
    copied from the original Jekyll templates and modified by trial
    and error to produce (what appears to be) the right answer.  If
    pages contain extra information, or if information is missing, the
    most likely cause is an error here.

1.  At the time of this commit, no styling is applied to the generated
    pages and they do not contain headers, footers, or navigation.
    All of this should be added once a general site theme is developed.

1.  `bin/gen.py` defines a `backtick` filter to convert backtick'd
    pieces of text to `<code>` blocks. This is currently *not* used in
    the Jinja templates because (a) the existing documentation
    includes the backticks as-is and (b) I couldn't be bothered to
    figure out how to add it to MkDocs.

Author: gvwilson

.gitignore

@@ -16,3 +16,8 @@ tags
 !.circleci
 !.gitignore
 !.npmignore
+
+docs
+ref_pages
+__pycache__
+tmp

Makefile

@@ -0,0 +1,95 @@
+all: commands
+
+BUNDLE=build/plotly.js
+OUT_DIR=docs
+SCHEMA=test/plot-schema.json
+REF_PAGES=ref_pages
+THEME=theme
+
+## site: rebuild with MkDocs
+site:
+	mkdocs build
+
+## pages: make all the pages
+pages:
+	python bin/gen.py \
+	--out docs \
+	--schema ${SCHEMA} \
+	--stubs ${REF_PAGES} \
+	--theme ${THEME}
+
+## figure: generate docs for a figure (annotations.html)
+figure:
+	python bin/gen.py \
+	--crash \
+	--out docs \
+	--schema ${SCHEMA} \
+	--stubs ${REF_PAGES} \
+	--theme ${THEME} \
+	annotations.md
+
+## global: generate docs for global (global.html)
+global:
+	python bin/gen.py \
+	--crash \
+	--out docs \
+	--schema ${SCHEMA} \
+	--stubs ${REF_PAGES} \
+	--theme ${THEME} \
+	global.md
+
+## subplot: generate docs for a subplot (polar.html)
+subplot:
+	python bin/gen.py \
+	--crash \
+	--out docs \
+	--schema ${SCHEMA} \
+	--stubs ${REF_PAGES} \
+	--theme ${THEME} \
+	polar.md
+
+## trace: generate docs for a trace (violin.html)
+trace:
+	python bin/gen.py \
+	--crash \
+	--out docs \
+	--schema ${SCHEMA} \
+	--stubs ${REF_PAGES} \
+	--theme ${THEME} \
+	violin.md
+
+## stubs: make reference page stubs
+stubs: ${SCHEMA}
+	python bin/make_ref_pages.py \
+	--pages ${REF_PAGES} \
+	--schema ${SCHEMA} \
+	--verbose
+
+## validate: check the generated HTML
+validate:
+	@html5validator --root docs
+
+## regenerate JavaScript schema
+schema:
+	npm run schema dist
+
+## -------- : --------
+## commands: show available commands
+# Note: everything with a leading double '##' and a colon is shown.
+commands:
+	@grep -h -E '^##' ${MAKEFILE_LIST} \
+	| sed -e 's/## //g' \
+	| column -t -s ':'
+
+## find-subplots: use jq to find subplot objects
+find-subplots:
+	@cat tmp/plot-schema-formatted.json | jq 'paths | select(.[length-1] == "_isSubplotObj")'
+
+## lint: check code and project
+lint:
+	@ruff check bin
+
+## clean: erase all generated content
+clean:
+	@find . -name '*~' -exec rm {} \;
+	@rm -rf ${REF_PAGES} ${OUT_DIR}

bin/gen.py

@@ -0,0 +1,97 @@
+"""Build plotly.js documentation using jinja template."""
+
+import argparse
+import frontmatter
+from jinja2 import Environment, FileSystemLoader
+from jinja2.exceptions import TemplateError
+import json
+import markdown
+from pathlib import Path
+import sys
+
+import plugins
+
+
+KEYS_TO_IGNORE = {
+    "_isSubplotObj",
+    "editType",
+    "role",
+}
+SUBPLOT = "_isSubplotObj"
+
+
+def main():
+    """Main driver."""
+    opt = parse_args()
+    schema = json.loads(Path(opt.schema).read_text())
+    env = Environment(loader=FileSystemLoader(opt.theme))
+    env.filters["backtick"] = plugins.backtick
+    env.filters["debug"] = plugins.debug
+    all_pages = opt.page if opt.page else [p.name for p in Path(opt.stubs).glob("*.md")]
+    err_count = 0
+    for page in all_pages:
+        if opt.crash:
+            render_page(opt, schema, env, page)
+        else:
+            try:
+                render_page(opt, schema, env, page)
+            except Exception as exc:
+                print(f"ERROR in {page}: {exc}", file=sys.stderr)
+                err_count += 1
+    print(f"ERRORS: {err_count} / {len(all_pages)}")
+
+
+def get_details(schema, page):
+    """Temporary hack to pull details out of schema and page header."""
+    # Trace
+    if "full_name" not in page:
+        return page
+
+    key = page["name"].split(".")[-1]
+    entry = schema["layout"]["layoutAttributes"][key]
+
+    # Subplot
+    if SUBPLOT in entry:
+        return entry
+
+    # Figure
+    return list(entry["items"].values())[0]
+
+
+def parse_args():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--crash", action="store_true", help="crash on first error")
+    parser.add_argument("--out", help="name of output directory")
+    parser.add_argument("--schema", required=True, help="path to schema JSON")
+    parser.add_argument("--stubs", required=True, help="path to stubs directory")
+    parser.add_argument("--theme", required=True, help="path to theme directory")
+    parser.add_argument("page", nargs="...", help="name(s) of source file in stubs directory")
+    return parser.parse_args()
+
+
+def render_page(opt, schema, env, page_name):
+    """Render a single page."""
+    stem = Path(page_name).stem
+    loaded = frontmatter.load(Path(opt.stubs, page_name))
+    metadata = loaded.metadata
+    assert "template" in metadata, f"page {page_name} does not specify 'template'"
+    content = loaded.content
+    details = get_details(schema, metadata)
+    template = env.get_template(metadata["template"])
+    html = template.render(
+        page={"title": stem, "meta": metadata},
+        config={"data": {"plot-schema": schema}},
+        details=details,
+        keys_to_ignore=KEYS_TO_IGNORE,
+        content=content,
+    )
+    if opt.out:
+        Path(opt.out, stem).mkdir(parents=True, exist_ok=True)
+        Path(opt.out, stem, "index.html").write_text(html)
+    else:
+        print(html)
+
+
+if __name__ == "__main__":
+    main()

bin/make_ref_pages.py

@@ -0,0 +1,125 @@
+"""Generate API reference pages from JSON metadata extracted from JavaScript source."""
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+# Suffix for generated files.
+SUFFIX = "md"
+
+# Attributes to document.
+ATTRIBUTES = [
+    "annotations",
+    "coloraxis",
+    "geo",
+    "images",
+    "map",
+    "mapbox",
+    "polar",
+    "scene",
+    "selections",
+    "shapes",
+    "sliders",
+    "smith",
+    "ternary",
+    "updatemenus",
+    "xaxis",
+    "yaxis",
+]
+
+# Template for documentation of attributes.
+ATTRIBUTE_TEMPLATE = """---
+template: attribute.jinja
+permalink: /javascript/reference/{full_attribute_path}/
+name: {attribute}
+full_name: {full_attribute}
+description: Figure attribute reference for Plotly's JavaScript open-source graphing library.
+parentlink: layout
+block: layout
+parentpath: layout
+---
+"""
+
+# Documenting top-level layout.
+GLOBAL_PAGE = """---
+template: global.jinja
+permalink: /javascript/reference/layout/
+name: layout
+description: Figure attribute reference for Plotly's JavaScript open-source graphing library.
+parentlink: layout
+block: layout
+parentpath: layout
+mustmatch: global
+---
+"""
+
+# Template for documentation of trace.
+TRACE_TEMPLATE = """---
+template: trace.jinja
+permalink: /javascript/reference/{trace}/
+trace: {trace}
+description: Figure attribute reference for Plotly's JavaScript open-source graphing library.
+---
+"""
+
+
+def main():
+    """Main driver."""
+    try:
+        opt = parse_args()
+        schema = json.loads(Path(opt.schema).read_text())
+        make_global(opt)
+        for attribute in ATTRIBUTES:
+            make_attribute(opt, attribute)
+        for trace in schema["traces"]:
+            make_trace(opt, trace)
+    except AssertionError as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
+
+
+def make_attribute(opt, attribute):
+    """Write reference pages for attributes."""
+    full_attribute = f"layout.{attribute}"
+    content = ATTRIBUTE_TEMPLATE.format(
+        full_attribute=full_attribute,
+        full_attribute_path=full_attribute.replace(".", "/"),
+        attribute=attribute,
+    )
+    write_page(opt, "attribute", f"{attribute}.{SUFFIX}", content)
+
+
+def make_global(opt):
+    """Make top-level 'global' page."""
+    write_page(opt, "global", f"global.{SUFFIX}", GLOBAL_PAGE)
+    
+
+
+def make_trace(opt, trace):
+    """Write reference page for trace."""
+    content = TRACE_TEMPLATE.format(trace=trace,)
+    write_page(opt, "trace", f"{trace}.{SUFFIX}", content)
+
+
+def parse_args():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--pages", required=True, help="where to write generated page stubs")
+    parser.add_argument("--schema", required=True, help="path to plot schema file")
+    parser.add_argument("--verbose", action="store_true", help="report progress")
+    return parser.parse_args()
+
+
+def write_page(opt, kind, page_name, content):
+    """Save a page."""
+    output_path = Path(f"{opt.pages}/{page_name}")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content)
+    if opt.verbose:
+        print(f"{kind}: {output_path}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

bin/plugins.py

@@ -0,0 +1,22 @@
+"""Jinja plugins."""
+
+import re
+import sys
+
+
+BACKTICK_RE = re.compile(r'`(.+?)`')
+def backtick(text):
+    """Regex replacement reordered."""
+    return BACKTICK_RE.sub(r"<code>\1</code>", text)
+
+
+def debug(msg):
+    """Print debugging message during template expansion."""
+    print(msg, file=sys.stderr)
+
+
+# If being loaded by MkDocs, register the filters.
+if "define_env" in globals():
+    def define_env(env):
+        env.filters["backtick"] = backtick
+        env.filters["debug"] = debug

bin/pretty-html.py

@@ -0,0 +1,6 @@
+"""Prettify HTML."""
+
+from bs4 import BeautifulSoup
+import sys
+
+sys.stdout.write(BeautifulSoup(sys.stdin.read(), "html.parser").prettify())

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: Plotly Libraries
+site_description: Documentation for Plotly libraries
+site_url: https://example.com
+copyright: Plotly Inc.
+
+docs_dir: ref_pages
+site_dir: docs
+theme:
+  name: null
+  custom_dir: theme
+
+plugins:
+  - exclude:
+      regex:
+        - '.*\.jinja'
+  - mkdocs-data-loader:
+      dir: dist
+      key: data

requirements.txt

@@ -0,0 +1,7 @@
+beautifulsoup4
+html5validator
+jinja2
+mkdocs
+mkdocs-exclude
+python-frontmatter
+ruff

src/components/errorbars/attributes.js

@@ -16,7 +16,7 @@ module.exports = {
         description: [
             'Determines the rule used to generate the error bars.',
 
-            'If *constant`, the bar lengths are of a constant value.',
+            'If *constant*, the bar lengths are of a constant value.',
             'Set this constant in `value`.',
 
             'If *percent*, the bar lengths correspond to a percentage of',