4bd85aa14161039a40fd499bd8416ab51f099d81
braney
  Sat Jul 25 18:34:48 2026 -0700
add Docent, a language for authoring Genome Browser tours refs #37892

A Docent script is an ordered list of high-level verbs (go, hide, track,
mouseover, convert, drag, shot) that drives a real browser against a real
server, and renders to a silent mp4 plus a named PNG still at every shot
marker.  One source, both outputs, so a published figure is a frame of the
tour and the two cannot drift apart.

The verbs encode browser mechanics rather than selectors.  convert: knows the
Hide-defaults checkbox reverts when the Assembly menu reloads, track: {clinvar:
pack} knows that composite's clean parameter set, and mouseover: knows a lifted
track's DOM id gains a per-run hub_<n>_ prefix.  The author writes intent.

The surface syntax is YAML so ordinary editors highlight it; the language is
the verb vocabulary on top, not the serialization.  Scripts are named
<base>.docent.yaml.

This was built inside the quickLift Current Protocols paper repo, where it
still has its six working scripts, and only the general parts move here: the
renderer, the language reference, and the make rules a project includes to get
incremental rebuilds.  Nothing in the build refers to the directory, the same
way cartTrackVarCatalog does not, since these are node scripts and need
playwright and js-yaml.

target: defaults to genome-test rather than the sandbox it grew up on, and
resolves any hgwdev-<user> name, so a script that forgets to say where it runs
does not quietly hit somebody's machine.

Next step is #37838.  Today a step reaches the browser as CGI variables, which
is why the verbs have to know each composite by heart; once the cart takes a
structured blob a step can name the state it wants instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

diff --git src/hg/utils/docent/docent.mk src/hg/utils/docent/docent.mk
new file mode 100644
index 00000000000..85c7a7e0537
--- /dev/null
+++ src/hg/utils/docent/docent.mk
@@ -0,0 +1,49 @@
+# Shared make rules for Docent tour scripts (see README.md in this directory).
+#
+# A project that keeps a set of *.docent.yaml scripts includes this file and gets
+# incremental rebuilds: each ../<base>.mp4 is regenerated when its own script — or
+# docent.js itself — is newer. docent.js writes the mp4 and the named stills in one
+# run, so the mp4 stands in for both as the make target.
+#
+# In the project's Makefile:
+#
+#     DOCENT ?= $(HOME)/kent/src/hg/utils/docent/docent.js
+#     include $(dir $(DOCENT))docent.mk
+#
+# then:
+#
+#     make            # build every mp4 whose script (or docent.js) changed
+#     make AP1        # build just ../AP1.mp4 (if stale)
+#     make -B AP2     # force a rebuild
+#     make list       # list the base names discovered
+#     make clean      # remove generated mp4s and stills/
+#
+# Override before the include: FIGDIR (where mp4s land, default ..), PW_ENV (the
+# Playwright runtime), SCRIPTS/BASES (to build an explicit subset).
+
+DOCENT  ?= $(HOME)/kent/src/hg/utils/docent/docent.js
+SCRIPTS ?= $(wildcard *.docent.yaml)
+BASES   ?= $(SCRIPTS:.docent.yaml=)
+FIGDIR  ?= ..
+MP4S    := $(addprefix $(FIGDIR)/,$(addsuffix .mp4,$(BASES)))
+
+# Shared Playwright/Chromium install. Anywhere you have playwright + js-yaml works;
+# at UCSC this is the ~/pwrec tree.
+PW_ENV  ?= PLAYWRIGHT_BROWSERS_PATH=$(HOME)/pwrec/browsers NODE_PATH=$(HOME)/pwrec/node_modules
+
+.PHONY: all list clean $(BASES)
+
+all: $(MP4S)
+
+$(FIGDIR)/%.mp4: %.docent.yaml $(DOCENT)
+	$(PW_ENV) node $(DOCENT) $<
+
+# Convenience: `make AP1` -> build ../AP1.mp4
+$(BASES): %: $(FIGDIR)/%.mp4
+
+list:
+	@echo $(BASES)
+
+clean:
+	rm -f $(MP4S)
+	rm -rf stills