Generate the glossary from the Allen Glossary repository - #253
Open
lappalainenj wants to merge 1 commit into
Open
Generate the glossary from the Allen Glossary repository#253lappalainenj wants to merge 1 commit into
lappalainenj wants to merge 1 commit into
Conversation
lappalainenj
force-pushed
the
feat-glossary-from-source
branch
2 times, most recently
from
August 18, 2026 00:10
722884d to
a8373e2
Compare
databook/glossary.md is maintained by hand today. This generates it from
AllenInstitute/allen-connectomics-glossary, which becomes the single
source of truth for the definitions. The databook only ever reads that
repository; nothing here writes back to it.
The page becomes 249 terms as cards with illustrations, a category legend
that doubles as a filter, and a search box. It stays a single MyST file,
so _toc.yml is untouched and the existing `- file: glossary` entry keeps
working. Cards are rendered at build time rather than in the browser, so
the page is complete HTML before any script runs.
scripts/build-glossary-page.mjs renders a glossary checkout into the page
.github/workflows/sync-glossary.yml regenerates it and opens a PR
.github/workflows/publish-glossary.yml publishes it without a capsule run
The glossary page executes nothing, so Actions can build it alone and put
the single resulting glossary.html on gh-pages; the other ~120 pages keep
whatever the last capsule run deployed. A definition fix therefore
reaches the site without waiting for a full rebuild, at the cost of the
glossary sometimes running slightly ahead of the rest of the book.
The publish workflow pins jupyter-book to 0.15.1, matching the capsule's
own environment file. The published page links against the _static bundle
already on gh-pages instead of shipping its own, so a mismatch renders it
against the wrong stylesheet and the theme chrome falls apart.
databook/glossary-aliases.json maps the spellings the databook writes
onto glossary term ids, since {term}`basket cell` has to reach an entry
called "Basket cell (BC)". Without it this change would leave 45
references unresolved; with it, 2. Mapping by id rather than display name
means rewording a term upstream cannot silently redirect a reference, and
a stale entry is skipped with a warning rather than failing the sync, so
one dead alias cannot freeze every future glossary update.
Against main this is a net wash on build warnings: GFP stops resolving,
and a duplicate ISI definition goes away.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lappalainenj
force-pushed
the
feat-glossary-from-source
branch
from
August 18, 2026 00:15
a8373e2 to
fbbbe78
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
databook/glossary.mdis maintained by hand today. This generates it fromAllenInstitute/allen-connectomics-glossary,
which becomes the single source of truth for the definitions. The databook only reads that
repository; nothing here writes back to it.
The page becomes 249 terms as cards with illustrations, a category legend that doubles as a
filter, and a search box. It stays a single MyST file, so
_toc.ymlis untouched.scripts/build-glossary-page.mjs.github/workflows/sync-glossary.yml.github/workflows/publish-glossary.ymlglossary.htmltogh-pagesThe glossary page executes nothing, so a definition fix reaches the site without waiting
for a capsule run; the other ~120 pages keep whatever the last capsule build deployed. A
capsule build simply overwrites the page with the same content, since it builds from
main.Two things worth a look
requirements.txtis now pinned. The published page links against the_staticbundlealready on
gh-pagesrather than shipping its own, so it has to be built by the same Sphinxgeneration as the rest of the site — otherwise it still builds but the theme chrome falls
apart, with header dropdowns rendering as bare bullet lists.
jupyter-book==0.15.1reproduces the deployed theme digest exactly. It is pinned in both
requirements.txtandthe publish workflow; change them together, capsule first.
databook/glossary-aliases.jsonmaps the spellings used here onto glossary term ids,since
{term}`basket cell`has to reach an entry called "Basket cell (BC)". Without it45 references would stop resolving; with it, 2 —
CSV, already unresolved onmain, andGFP, which the glossary does not define yet. Net warnings are unchanged frommain:GFPstops resolving, and a duplicateISIdefinition goes away.Verified
Full book builds with
jb build -n --keep-going: 56 warnings, the same asmain.Rendered on a fork serving the whole databook, executed notebooks included:
https://lappalainenj.github.io/allenswdb.github.io/glossary.html
databook/glossary.mdis generated and carries a do-not-edit header — corrections belongupstream in the glossary repository.