docs: schema 2.1 guide, codes, changelog, and report

A guide page for the four registries: where entries live, how targets
point at them, the other new fields, the brace-reference table, what
students never see, the lecture and glossary pages, every new error and
lint rule, and the migration from terms.yaml and values.yaml. The setup
guide points at it.

The README covers glossary.yaml, the nine schemas, the 2.1 checks, the
glossary lint family and the note severity, the new lecture commands and
report sections, migrate glossary, and schema version 2.1. Module docs
and the changelog follow.

docs/design/2.1/CODES.md maps the specification's E, W, and I codes to
coursebank's messages and lint codes, each with its test, and REPORT.md
records what changed, the two remaining schema differences, every choice
made where the specification left room, and suggested changes to it. A
new test covers the validation messages the specification does not
number.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-11-16 12:31:01 -05:00
1 parent 6c07122fc5
commit b5cae6afac
11 files changed
+535 -29

No files matched your search

+2 -2
View File
@@ -7,8 +7,8 @@
//! The three modules here are what you interact with before an exam exists, and
//! they divide by how much authority each one has.
//!
//! [`lint`] has none. Its 26 rules are advice with stable codes, every one
//! silenceable with `--ignore`. It is deliberately separate from the validation in
//! [`lint`] has none. Its 44 rules are advice with stable codes, every one
//! silenceable with `--ignore`, and the two that report notes never fail. It is deliberately separate from the validation in
//! [`crate::model::bank`], which enforces what must be true and fails. Conflating
//! the two produces a tool that either blocks you on style or lets real errors
//! through.
+11 -5
View File
@@ -16,14 +16,16 @@
//!
//! 1. [`setup`] builds a course directory from nothing and explains what each file
//! is for.
//! 2. [`authoring`] writes items, with the design fields that make an item worth
//! 2. [`glossary`] adds the terms, equations, values, and misconceptions a
//! course's targets turn on, and the lecture pages built from them.
//! 3. [`authoring`] writes items, with the design fields that make an item worth
//! reusing.
//! 3. [`first_exam`] runs one exam end to end: assemble, export, administer,
//! 4. [`first_exam`] runs one exam end to end: assemble, export, administer,
//! ingest, analyze, report.
//! 4. [`typst_export`] covers printed output, template markers, and render config.
//! 5. [`assignment`] publishes a homework to the course website, with solutions
//! 5. [`typst_export`] covers printed output, template markers, and render config.
//! 6. [`assignment`] publishes a homework to the course website, with solutions
//! gated behind a password.
//! 6. [`recipes`] holds short answers to specific questions, for when you already
//! 7. [`recipes`] holds short answers to specific questions, for when you already
//! know the shape of the tool.
//!
//! ## Why the tutorials are in here rather than a wiki
@@ -45,6 +47,10 @@
#[doc = include_str!("../docs/guide/setup.md")]
pub mod setup {}
/// Terms, equations, values, and misconceptions, and the pages built from them.
#[doc = include_str!("../docs/guide/glossary.md")]
pub mod glossary {}
/// Writing items that are worth keeping.
#[doc = include_str!("../docs/guide/authoring.md")]
pub mod authoring {}
+8 -5
View File
@@ -20,13 +20,14 @@
//! |:--|:--|:--|
//! | `course.yaml` | identity, policy, units | you |
//! | `references.yaml` | the works the course cites | you |
//! | `lectures/*.yaml` | one lecture: readings, and what it teaches | you |
//! | `objectives/*.yaml` | one objective and its learning targets | you |
//! | `glossary.yaml` | terms, equations, values, and misconceptions no one objective owns | you, or `migrate glossary` |
//! | `lectures/*.yaml` | one lecture: readings, materials, and what it teaches | you |
//! | `objectives/*.yaml` | one objective, its learning targets, and the glossary entries they first need | you |
//! | `banks/*.yaml` | items, with design intent and pooled statistics | you, then `calibrate` |
//! | `assessments/*.yaml` | what was given, to whom, when | `assemble`, then you |
//! | `data/*.parquet` | one row per student per item | `ingest` |
//!
//! The first four are one course file split by subject; `coursebank course build`
//! The first five are one course file split by subject; `coursebank course build`
//! prints the merged result, and a course that keeps everything in `course.yaml`
//! still loads unchanged. See [`course::fragment`].
//!
@@ -75,8 +76,10 @@
//!
//! ## Dependency posture
//!
//! Deliberately small: serde, a YAML parser, clap, thiserror, and csv, plus arrow
//! and parquet behind a default-on feature that can be switched off. Dates, PRNG,
//! Deliberately small: serde, a YAML parser, clap, thiserror, csv, and regex
//! (built without its optional features, for the glossary's `conflicts` and
//! `target_text_forbid` patterns), plus arrow and parquet behind a default-on
//! feature that can be switched off. Dates, PRNG,
//! hashing, ZIP writing, and the psychometrics are implemented here rather than
//! pulled in — see [`date`], [`rng`], [`hash`], [`zipfile`], [`irt`]. For a tool
//! whose job is to still open a course repository in five years, that tradeoff
+3 -1
View File
@@ -13,8 +13,10 @@
//! taxonomy levels, cognitive processes, error types, status, flags
//! │
//! course identity, policy, objectives, lectures, stimuli
//! │ ├─ course::glossary terms, equations, values, misconceptions
//! │ └─ course::fragment merges course.yaml, references.yaml,
//! │ lectures/*.yaml, objectives/*.yaml
//! │ glossary.yaml, lectures/*.yaml,
//! │ objectives/*.yaml
//! │
//! item one question: stem, options, design intent, calibration
//! │