Friendly 5-minute intro landing page

2026-05-31 · docs/intro.html · branch docs/friendly-intro-page

Why

A new user landing on the GitHub repo or the docs site needed an obvious "start here" — a guided tour rather than a Sphinx API ref. This adds one hand-curated, self-contained HTML page that gives the toolbox a friendly entry point with runnable code, the nstat.extras tour, and the paper-example gallery.

What shipped

docs/intro.html — a self-contained page (embedded CSS, light/dark aware) with: hero, install commands, six capability cards each carrying a 5-10 line snippet using real public symbols, a tour of every nstat.extras subpackage, the paper-example thumbnail gallery (Examples 1-5), and a "Where to next" link panel. Published at /intro.html via html_extra_path.
README.md — new top-of-readme callout pointing visitors at the intro.
extras_summary.html — small «-back link and refreshed header pointing back to the intro for guided navigation.
tests/test_intro_page.py — 5 drift guards: file exists, registered in html_extra_path, README link present, every name-dropped public symbol is in nstat.__all__, and the gallery PNGs actually resolve under docs/figures/example*/.

The six capability cards

#	Card	Symbols used	Pointer for figures
1	Build a spike train	`nspikeTrain`	`notebooks/nSpikeTrainExamples.ipynb`
2	Assemble a Trial	`Trial` · `Covariate` · `nstColl`	`notebooks/TrialExamples.ipynb`
3	Poisson GLM + KS	`Analysis.GLMFit` · `FitResult.computeKSStats`	Paper Example 2 (thalamic whisker GLM)
4	Population GOF	`population_time_rescale`	inline (Tier 1.1)
5	State-space EM	`fit_point_process_em_best_of`	`examples/extras/em_dynamax_demo.py`
6	Clusterless decoding	`fit_clusterless_decoder`	`examples/extras/decoding_clusterless_demo.py`

Verification

Check	Result
`tests/test_intro_page.py` (5 drift guards)	PASS
`make readme-check`	PASS
`make helpfile-check`	PASS
`make docs-strict` (two-pass `-W`)	PASS
Sphinx `/index.html` intact; `/intro.html` publishes	verified

Files changed

New: docs/intro.html, tests/test_intro_page.py, docs/changes/2026-05-31-friendly-intro.html
Modified: docs/conf.py (html_extra_path += intro.html), README.md (top callout), docs/extras_summary.html (back-link + cross-reference), docs/changes/whats_new.html (new entry)