Skip to content

Build the interactive demo with artesian - #25

Open
awickert wants to merge 5 commits into
masterfrom
docs/use-artesian
Open

Build the interactive demo with artesian#25
awickert wants to merge 5 commits into
masterfrom
docs/use-artesian

Conversation

@awickert

@awickert awickert commented Sep 1, 2026

Copy link
Copy Markdown
Collaborator

Builds the interactive browser demo with artesian instead of the hand-rolled block in docs/conf.py.

Why

The 43 lines in conf.py that wheeled GRLP, downloaded and self-hosted the panel/bokeh wheels, ran panel convert, and rewrote the holoviz CDN URLs were never GRLP-specific. They are now maintained once, in MNiMORPH/artesian, where their two upstream workarounds are covered by tests:

  • the holoviz CDN's bokeh wheel returns HTTP 403, so the wheel URLs must be rewritten to co-located copies;
  • panel convert can print a failure and still exit 0, which previously meant a missing demo with no error anywhere in the build.

What changed

conf.py drops the block in favour of an extension and a config entry:

extensions = ["artesian.sphinxext", ...]

artesian_apps = [
    {"app": "../interactive_demo/grlp_panel.py",
     "packages": [".."],
     "requirements": ["numpy", "scipy", "networkx"],
     "outdir": "_static/interactive"},
]

The remaining commits are documentation the change made stale:

  • grlp_panel.py's docstring documented a raw panel convert invocation.
  • interactive_demo/README.md described only the JupyterLite notebooks, never mentioned grlp_panel.py, and stated that these demos are "deliberately kept out of the ReadTheDocs site" — untrue since the Panel demo was published. Re-led on the demo that actually ships; the notebooks' own instructions and test checklist are unchanged.
  • CHANGELOG.md [Unreleased] claimed the demo "depends on no external services at run time". It does: the Pyodide runtime is fetched from cdn.jsdelivr.net on first load, and panel convert hardcodes that URL. Self-hosting the wheels removes the wheel CDN, not the runtime one. Corrected before it could ship in the v3.0.0 changelog.

Verification

A full docs build was run against this branch and compared with the committed reference in docs/_static/interactive/:

  • grlp_panel.js — the application itself — is identical once version numbers are normalized.
  • grlp_panel.html differs on exactly 16 lines: 10 per-build UUIDs and 6 lines of panel's own 1.9.3 → 1.9.4 spinner CSS. Nothing attributable to this change.

Note before merging

docs/requirements.txt pins artesian @ git+https://github.com/MNiMORPH/artesian@main, because artesian is not yet on PyPI. This should become an ordinary version specifier at artesian's first release (tracked in MNiMORPH/artesian).

🤖 Generated with Claude Code

Replaces 43 lines of wheel-building, panel convert invocation and CDN URL
rewriting in conf.py with the artesian.sphinxext extension and an
artesian_apps entry. The machinery was never GRLP-specific; it is now
maintained once, in MNiMORPH/artesian, where its two upstream workarounds
(the holoviz bokeh 403, and panel convert failing while exiting 0) are
tested.

Verified against the previous output: the generated grlp_panel.js is
identical once version numbers are normalized. grlp_panel.html differs on 16
lines, all accounted for -- 10 per-build UUIDs and 6 lines of panel's own
1.9.3 to 1.9.4 spinner CSS.

Drops the now-unused glob and subprocess imports.
Replaces the direct panel pin; artesian pulls panel, which pulls bokeh.
Pinned to a git ref because artesian is not yet on PyPI -- this should
become a normal version specifier at its first release.
The build command in the docstring no longer describes how this app is
built; conf.py drives it through artesian. Gives the equivalent one-line
artesian invocation for building it by hand.
The file described only the JupyterLite notebooks and never mentioned
grlp_panel.py, which is the demo published on Read the Docs. It also stated
two things that are no longer true: that these demos are deliberately kept
out of the RTD site, and that the route in would be jupyterlite-sphinx.

Leads with the Panel demo and how artesian builds it, demotes the notebooks
to the classroom variant they now are, and corrects the status notes rather
than appending to them. The notebooks' own instructions and test checklist
are unchanged; the WASM-verification note now distinguishes the Panel demo
(verified, published) from the notebooks (still unverified).
The [Unreleased] demo entry said the demo 'depends on no external services
at run time'. It does: the Pyodide runtime is fetched from cdn.jsdelivr.net
on first load, and panel convert hardcodes that URL. Self-hosting the wheels
removes the wheel CDN, not the runtime one. Better caught now than in the
v3.0.0 changelog.

Also names artesian as the builder rather than a bare panel convert.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant