[jdkent]

Publishes https://neurostuff.github.io/study_schema/ (Pages is already enabled with build_type workflow).

What

• tools/build_docs.py runs LinkML gen-doc on the storage, extraction and paper-parse schemas (every class, slot and enum, with links and mermaid diagrams; the evidence schema is imported by extraction and documented with it) into build/docs/reference/<schema>/, and stages the guides beside it. build/ is git-ignored; nothing generated is committed.
• mkdocs.yml (mkdocs-material, search on). Navigation: Home (README), Guides (schema tutorial, analysis entities, representing models, storage design notes, extraction schema), Crosswalks (standards, ARS), Reference (storage, extraction, paper parse). Class, slot and enum pages are reachable from each reference index and from search.
• docs extra in pyproject.toml (mkdocs>=1.6,<2, mkdocs-material>=9.5, linkml>=1.12). mkdocs is held below 2 because Material warns that 2.0 drops plugins and theme overrides.
• .github/workflows/docs.yml: pull requests build with mkdocs build --strict; pushes to main build, then deploy with upload-pages-artifact and deploy-pages (deploy job has pages: write, id-token: write, contents: read; a pages concurrency group). contracts.yml is untouched.

Links. The script rewrites links while staging the guides, so the markdown keeps working on GitHub: README becomes the home page, links to a schema directory go to its reference index, other repository files go to GitHub. A link to a file that does not exist is left alone, so mkdocs build --strict fails on it. Five such links in the guides (the expressivity probe, the multivariate probe, the ONVOC audit, test_effect_kind_derivation.py, a corrections JSON) were removed at the source; two of them were rows in the README's table of documents.

Checked. Built on a fresh clone with a fresh venv: build_docs.py then mkdocs build --strict passes. Read the rendered Analysis class page (mermaid class diagram, slot links), the AnalysisType enum page and the schema tutorial (guide-to-guide and reference links).

Notes

• gen-doc writes a slot analysis.md and a class Analysis.md in the same folder, so a local preview on a case-insensitive filesystem would collide; the Linux CI build is unaffected.
• gen-doc shows None in the Meaning column of enums whose values have no meaning.
• Not touching README or the LinkML descriptions beyond the build, so this does not conflict with Drop the C2/C3 contract labels #47.

🤖 Generated with Claude Code

[jdkent]

LGTM