education/coursebank
1
0
Fork 0
Code Issues Pull Requests Actions Releases 1 Activity

feat: improve typst handling

Browse Source
This commit is contained in:
alexm
2026-08-06 16:45:50 -04:00
parent 09c3222f8d
commit 07e3131f17
19 changed files with 4148 additions and 416 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/export/typst.rs
+283 -353
View File
@@ -5,40 +5,78 @@
//! iterate on. `pixi run -e docs typst compile` turns the output of this module
//! into a PDF.
//!
//! The emitted document is deliberately plain and self-contained: no imports, no
//! template packages, nothing that can break because a package version moved. It
//! is also meant to be edited. A generated exam is a starting point, and the
//! output is formatted so that a human can reasonably open it and adjust spacing
//! before printing.
//! ## What changed, and why
//!
//! Every export takes a form, so form B's answer key is generated from the same
//! permutation that produced form B's question paper. Keeping the key and the
//! paper in one code path is the only way to be sure they agree — a mismatch is
//! discovered by twenty-five students at once.
//! This module used to build a document with `format!`. That made the position of
//! the points label a Rust change, put a `#grid` call in a match arm, and meant
//! the only way to move something on the page was to fork the crate. It also made
//! a generated exam a dead end: you could edit the output, but the next export
//! overwrote the edit.
//!
//! So the tool no longer writes documents. It loads a Typst file that you own,
//! finds the markers in it, and injects data:
//!
//! ```typst
//! // coursebank:begin questions
//! #render-question((number: 1, stem: [Sample.], options: ()))
//! // coursebank:end questions
//! ```
//!
//! `render-question` is defined in your template. What the payload contains is
//! governed by [`config::RenderConfig`]; where it lands and how it looks is
//! governed by the template. The default templates are compiled into the binary,
//! and `coursebank template dump` writes them into `templates/` so that
//! customizing means editing a file. See [`template`] for the marker syntax, the
//! slot list, and the lookup order.
//!
//! ## What is still enforced here
//!
//! Two invariants survived the rewrite, because both are the kind of mistake a
//! room full of students discovers simultaneously.
//!
//! **A form's key is derived from the same permutation as its paper.** Option order
//! comes from [`select::option_order`](crate::select::option_order) against the
//! form's recorded seed, never from anything stored, so every export of form B
//! agrees with every other. The paper, the key, and the answer sheet are all built
//! from one [`payload::Payload`].
//!
//! **The paper's payload does not contain the answer.** Not `correct: false`, not a
//! flag to check — the field is absent. See [`config::Reveal`]. A template cannot
//! leak what it was never given, and that stays true through every future edit of
//! the template by someone who has not read this comment.
pub mod config;
pub mod payload;
pub mod template;
pub mod value;
use std::path::{Path, PathBuf};
pub use config::{
ConfigFile, ContentMode, Fields, LetterStyle, Overrides, RenderConfig, Reveal, StimulusMode,
Variant, CONFIG_FILE, CONFIG_TEMPLATE,
};
pub use payload::Payload;
pub use template::{Origin, Slot, Template};
pub use value::Value;
use crate::assessment::{AssessmentFile, Form};
use crate::catalog::Catalog;
use crate::course::CourseFile;
use crate::course::Layout;
use crate::error::{Error, Result};
use crate::markup;
use crate::select;
/// Options for a printed exam.
/// What to render.
#[derive(Debug, Clone)]
pub struct Options {
/// Which form to render.
/// Which form.
pub form: Form,
/// Whether to leave a name and student-id block at the top.
pub name_block: bool,
/// Whether to show the points each question is worth.
pub show_points: bool,
/// Whether to start each question on a new page. Occasionally worth it for an
/// exam with long stimuli.
pub page_per_item: bool,
/// Paper size, as Typst names it.
pub paper: String,
/// Base font size.
pub font_size: String,
/// Which document.
pub variant: Variant,
/// A template path that overrides the usual lookup. Takes precedence over
/// `template` in the render config.
pub template: Option<PathBuf>,
/// What to put in the payload, and how.
pub config: RenderConfig,
}
impl Default for Options {
@@ -50,22 +88,195 @@ impl Default for Options {
shuffle_items: false,
shuffle_options: false,
},
name_block: true,
show_points: true,
page_per_item: false,
paper: "us-letter".to_string(),
font_size: "11pt".to_string(),
variant: Variant::Exam,
template: None,
config: RenderConfig::for_variant(Variant::Exam),
}
}
}
/// Renders the question paper.
impl Options {
/// Options for one variant, with that variant's default configuration.
///
/// # Arguments
///
/// * `variant` - which document.
/// * `form` - the form to render.
///
/// # Returns
///
/// The options.
pub fn new(variant: Variant, form: Form) -> Options {
Options {
form,
variant,
template: None,
config: RenderConfig::for_variant(variant),
}
}
/// The template path to use, preferring the explicit one.
fn template_path(&self) -> Option<&Path> {
self.template.as_deref().or(self.config.template.as_deref())
}
}
/// A finished document, with everything a caller needs to explain it.
#[derive(Debug, Clone)]
pub struct Rendered {
/// Which document this is.
pub variant: Variant,
/// Where the template came from.
pub origin: Origin,
/// Which slots the template declared and this render filled.
pub slots: Vec<Slot>,
/// The Typst source.
pub text: String,
/// The payload, kept so a caller can also write it as JSON without rebuilding.
pub payload: Payload,
/// Advisory problems: markup that will probably confuse the Typst compiler, and
/// a template that declared no markers at all.
pub warnings: Vec<String>,
}
/// Renders one document.
///
/// # Arguments
///
/// * `catalog` - the loaded course.
/// * `record` - the assessment record.
/// * `opts` - rendering options.
/// * `opts` - what to render.
///
/// # Returns
///
/// The finished document.
///
/// # Errors
///
/// Returns [`Error::Unresolved`] when a placement references a missing item,
/// [`Error::Io`] when an explicitly requested template cannot be read, and
/// [`Error::Invalid`] when the template's markers are malformed or every placement
/// is marked dropped.
pub fn render(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<Rendered> {
let template = template::load(
&catalog.layout,
opts.variant,
Some(record.assessment.id.as_str()),
opts.template_path(),
)?;
let payload = payload::build(catalog, record, &opts.form, &opts.config)?;
if payload.questions.is_empty() {
return Err(Error::Invalid(vec![
"this assessment has no printable items; every placement is marked dropped".to_string(),
]));
}
// Only build what the template asked for. A paper template that never mentions
// `data` should not pay for a second copy of every stem.
let mut bodies = Vec::new();
if template.wants(Slot::Meta) {
bodies.push((Slot::Meta, payload::meta_body(&payload, &opts.config)));
}
if template.wants(Slot::Questions) {
bodies.push((
Slot::Questions,
payload::questions_body(&payload, &opts.config),
));
}
if template.wants(Slot::Data) {
bodies.push((Slot::Data, payload::data_body(&payload, &opts.config)));
}
let mut warnings = payload::check(&payload, &opts.config);
if template.is_inert() {
warnings.push(format!(
"the template {} declares no coursebank markers, so no questions were injected; add \
`// coursebank:questions` where they belong",
template.origin
));
}
Ok(Rendered {
variant: opts.variant,
origin: template.origin.clone(),
slots: template.slots(),
text: template.render(&bodies),
payload,
warnings,
})
}
/// Builds the payload without rendering a template.
///
/// For writing the questions out as JSON, which is what a hand-written Typst exam
/// that already calls `json("questions.json")` wants.
///
/// # Arguments
///
/// * `catalog` - the loaded course.
/// * `record` - the assessment record.
/// * `opts` - what to render; only the form and config are consulted.
///
/// # Returns
///
/// The payload.
///
/// # Errors
///
/// Returns [`Error::Unresolved`] when a placement references a missing item.
pub fn build_payload(
catalog: &Catalog,
record: &AssessmentFile,
opts: &Options,
) -> Result<Payload> {
payload::build(catalog, record, &opts.form, &opts.config)
}
/// The path a course's Typst configuration lives at.
///
/// # Arguments
///
/// * `layout` - the course layout.
pub fn config_path(layout: &Layout) -> PathBuf {
template::dir(layout).join(CONFIG_FILE)
}
/// Loads a course's Typst configuration.
///
/// # Arguments
///
/// * `layout` - the course layout.
///
/// # Returns
///
/// The parsed config file, or an empty one when `templates/typst.yaml` is absent.
/// Absence is not an error: a course that has never customized anything should
/// export without being told to write a config file first.
///
/// # Errors
///
/// Returns [`Error::Yaml`] when the file exists but does not parse.
pub fn load_config(layout: &Layout) -> Result<ConfigFile> {
let path = config_path(layout);
if path.is_file() {
crate::yaml::read(&path)
} else {
Ok(ConfigFile::default())
}
}
/// Renders the question paper.
///
/// Kept so existing callers keep working. New code should use [`render`], which
/// also reports which template was used and what it warned about.
///
/// # Arguments
///
/// * `catalog` - the loaded course.
/// * `record` - the assessment record.
/// * `opts` - rendering options; the variant is forced to [`Variant::Exam`].
///
/// # Returns
///
@@ -73,120 +284,9 @@ impl Default for Options {
///
/// # Errors
///
/// Returns [`Error::Unresolved`] when a placement references a missing item.
/// As [`render`].
pub fn exam(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<String> {
let course = &catalog.course;
let mut out = String::new();
out.push_str(&preamble(course, record, opts));
if opts.name_block {
out.push_str(
"#block(above: 1em, below: 1.5em)[\n \
#grid(columns: (auto, 1fr, auto, 1fr), gutter: 0.6em,\n \
[*Name*], [#box(width: 100%, repeat[.])],\n \
[*Student ID*], [#box(width: 100%, repeat[.])],\n )\n]\n\n",
);
}
if let Some(instructions) = &record.assessment.instructions {
out.push_str(&format!(
"#block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%)[\n {}\n]\n\n",
markup::to_typst(instructions)
));
}
let default_points = course.policy.points_per_item;
let mut printed = 0usize;
for placement in select::layout(record, &opts.form) {
if placement.dropped {
continue;
}
let entry = catalog.require(&placement.item)?;
let item = &entry.item;
printed += 1;
if opts.page_per_item && printed > 1 {
out.push_str("#pagebreak()\n\n");
}
// A stimulus shared by several items is printed with each of them. That
// repeats material, but a student should never have to flip pages to find
// the passage a question refers to.
if let Some(id) = &item.stimulus {
if let Some(stimulus) = course.stimuli.get(id) {
out.push_str(&format!(
"#block(stroke: 0.5pt + luma(180), inset: 8pt, radius: 3pt, width: 100%)[\n \
{}\n]\n",
markup::to_typst(&stimulus.body)
));
if let Some(caption) = &stimulus.caption {
out.push_str(&format!(
"#block(above: 0.3em)[#text(size: 0.85em, style: \"italic\")[{}]]\n",
markup::to_typst(caption)
));
}
}
}
let points = placement
.points
.unwrap_or_else(|| item.points(default_points));
let label = if placement.bonus {
if opts.show_points {
format!(
" #text(fill: rgb(\"#666666\"))[(bonus, {})]",
plural_points(points)
)
} else {
" #text(fill: rgb(\"#666666\"))[(bonus)]".to_string()
}
} else if opts.show_points {
format!(
" #text(fill: rgb(\"#666666\"))[({})]",
plural_points(points)
)
} else {
String::new()
};
// The question number is the recorded one, not the printed position, so a
// scanned answer sheet still joins to the assessment record.
out.push_str(&format!(
"#block(above: 1.2em, below: 0.5em)[*{}.*{label} {}]\n",
placement.number,
markup::to_typst(&item.stem)
));
if item.is_multi_key() {
out.push_str(
"#block(below: 0.4em)[#text(size: 0.9em, style: \"italic\")[Select all that \
apply.]]\n",
);
}
let order = select::option_order(&opts.form, &placement.item, item.options.len());
out.push_str("#block(inset: (left: 1.2em))[\n");
for (position, source_index) in order.iter().enumerate() {
let choice = &item.options[*source_index];
// Options are relabeled by printed position, so a shuffled form still
// reads A, B, C, D.
let letter = (b'A' + position as u8) as char;
out.push_str(&format!(
" #grid(columns: (1.4em, 1fr), gutter: 0.2em)[{letter}.][{}]\n",
markup::to_typst(&choice.text)
));
}
out.push_str("]\n\n");
}
if printed == 0 {
return Err(Error::Invalid(vec![
"this assessment has no printable items; every placement is marked dropped".to_string(),
]));
}
Ok(out)
render_variant(catalog, record, opts, Variant::Exam)
}
/// Renders the answer key.
@@ -195,7 +295,7 @@ pub fn exam(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Resul
///
/// * `catalog` - the loaded course.
/// * `record` - the assessment record.
/// * `opts` - rendering options, whose form determines the letters.
/// * `opts` - rendering options; the variant is forced to [`Variant::Key`].
///
/// # Returns
///
@@ -203,107 +303,18 @@ pub fn exam(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Resul
///
/// # Errors
///
/// Returns [`Error::Unresolved`] when a placement references a missing item.
/// As [`render`].
pub fn answer_key(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<String> {
let mut out = String::new();
out.push_str(&format!(
"#set page(paper: \"{}\", margin: 2cm)\n#set text(size: 10pt)\n\n\
= {} — answer key (form {})\n\n",
opts.paper,
escape(&record.assessment.title),
opts.form.id
));
out.push_str(
"#text(size: 0.9em, style: \"italic\")[Letters below are the letters *as printed on this \
form*. Do not use this key on another form.]\n\n",
);
out.push_str(
"#table(\n columns: (auto, auto, auto, 1fr),\n align: (right, center, center, left),\n \
table.header([*\\#*], [*Key*], [*Level*], [*Objectives*]),\n",
);
for placement in select::layout(record, &opts.form) {
if placement.dropped {
continue;
}
let entry = catalog.require(&placement.item)?;
let item = &entry.item;
let order = select::option_order(&opts.form, &placement.item, item.options.len());
// Map the source option index to the letter it was printed as.
let mut printed_letters = Vec::new();
for (position, source_index) in order.iter().enumerate() {
if item.options[*source_index].correct {
printed_letters.push(((b'A' + position as u8) as char).to_string());
}
}
let objectives = if placement.learning_objectives.is_empty() {
item.learning_objectives.join(", ")
} else {
placement.learning_objectives.join(", ")
};
out.push_str(&format!(
" [{}], [*{}*], [{}], [{}],\n",
placement.number,
printed_letters.join(""),
placement
.level
.map(|l| l.code().to_string())
.unwrap_or_else(|| "-".into()),
escape(&objectives)
));
}
out.push_str(")\n\n");
// Partial credit decisions belong on the key, where the grader will see them.
let overrides: Vec<String> = record
.items
.iter()
.filter(|p| !p.credit_overrides.is_empty())
.map(|p| {
let list: Vec<String> = p
.credit_overrides
.iter()
.map(|(letter, credit)| format!("{letter} = {:.0}%", credit * 100.0))
.collect();
format!("Question {}: {}", p.number, list.join(", "))
})
.collect();
if !overrides.is_empty() {
out.push_str("== Partial credit\n\n");
for line in overrides {
out.push_str(&format!("- {}\n", escape(&line)));
}
out.push('\n');
}
let dropped: Vec<String> = record
.items
.iter()
.filter(|p| p.dropped)
.map(|p| p.number.to_string())
.collect();
if !dropped.is_empty() {
out.push_str(&format!(
"== Dropped\n\nQuestion(s) {} were dropped and are not printed.\n\n",
dropped.join(", ")
));
}
Ok(out)
render_variant(catalog, record, opts, Variant::Key)
}
/// Renders a bubble sheet matching the form.
///
/// # Arguments
///
/// * `catalog` - the loaded course, for option counts.
/// * `catalog` - the loaded course.
/// * `record` - the assessment record.
/// * `opts` - rendering options.
/// * `opts` - rendering options; the variant is forced to [`Variant::AnswerSheet`].
///
/// # Returns
///
@@ -311,132 +322,51 @@ pub fn answer_key(catalog: &Catalog, record: &AssessmentFile, opts: &Options) ->
///
/// # Errors
///
/// Returns [`Error::Unresolved`] when a placement references a missing item.
/// As [`render`].
pub fn bubble_sheet(catalog: &Catalog, record: &AssessmentFile, opts: &Options) -> Result<String> {
let mut out = format!(
"#set page(paper: \"{}\", margin: 1.5cm)\n#set text(size: 10pt)\n\n\
= {} — answer sheet (form {})\n\n\
#grid(columns: (auto, 1fr, auto, 1fr), gutter: 0.6em,\n \
[*Name*], [#box(width: 100%, repeat[.])],\n \
[*Student ID*], [#box(width: 100%, repeat[.])],\n)\n\n\
#v(1em)\n",
opts.paper,
escape(&record.assessment.title),
opts.form.id
);
render_variant(catalog, record, opts, Variant::AnswerSheet)
}
out.push_str("#columns(2)[\n");
for placement in select::layout(record, &opts.form) {
if placement.dropped {
continue;
}
let entry = catalog.require(&placement.item)?;
let count = entry.item.options.len();
let bubbles: Vec<String> = (0..count)
.map(|i| {
let letter = (b'A' + i as u8) as char;
format!("#circle(radius: 0.42em, stroke: 0.5pt)[#align(center + horizon)[#text(size: 0.7em)[{letter}]]]")
})
.collect();
out.push_str(&format!(
" #block(below: 0.45em)[#box(width: 2em)[{}.] {}]\n",
placement.number,
bubbles.join(" ")
));
/// Renders one variant, substituting that variant's default config when the caller
/// passed the config for a different one.
fn render_variant(
catalog: &Catalog,
record: &AssessmentFile,
opts: &Options,
variant: Variant,
) -> Result<String> {
let mut opts = opts.clone();
if opts.variant != variant {
// The caller asked for a different document than the config describes, so
// the config's `reveal` almost certainly belongs to the other one. Taking
// the variant's own default is the safe reading, and the direction that
// matters is the paper: never inherit a key's `reveal`.
opts.config = RenderConfig::for_variant(variant);
opts.variant = variant;
}
out.push_str("]\n");
Ok(out)
}
/// Builds the document preamble.
///
/// # Arguments
///
/// * `course` - the course.
/// * `record` - the assessment record.
/// * `opts` - rendering options.
///
/// # Returns
///
/// Typst setup and a title block.
fn preamble(course: &CourseFile, record: &AssessmentFile, opts: &Options) -> String {
let form_note = if record.forms.len() > 1 {
format!(" · Form {}", opts.form.id)
} else {
String::new()
};
let date = record
.assessment
.date
.map(|d| d.to_string())
.unwrap_or_default();
let minutes = record
.assessment
.minutes_allowed
.map(|m| format!(" · {m:.0} minutes"))
.unwrap_or_default();
format!(
"#set page(\n paper: \"{paper}\",\n margin: 2cm,\n \
header: [#text(size: 0.85em)[{code} · {title}{form_note}]],\n \
footer: context [#text(size: 0.85em)[Page #counter(page).display() of \
#counter(page).final().first()]],\n)\n\
#set text(size: {size})\n\
#set par(justify: false, leading: 0.65em)\n\n\
#align(center)[\n #text(size: 1.4em, weight: \"bold\")[{title}]\n \\\n \
#text(size: 0.95em)[{code} — {course_title} · {term}]\n \\\n \
#text(size: 0.9em)[{date}{minutes}]\n]\n\n",
paper = opts.paper,
size = opts.font_size,
code = escape(&course.course.code),
course_title = escape(&course.course.title),
term = escape(
record
.assessment
.term
.as_deref()
.unwrap_or(&course.course.term)
),
title = escape(&record.assessment.title),
form_note = form_note,
date = date,
minutes = minutes,
)
}
/// Formats a point value with the right plural.
fn plural_points(points: f64) -> String {
if (points - 1.0).abs() < 1e-9 {
"1 point".to_string()
} else if (points.fract()).abs() < 1e-9 {
format!("{points:.0} points")
} else {
format!("{points} points")
}
}
/// Escapes text for Typst content mode.
fn escape(s: &str) -> String {
markup::to_typst(s)
Ok(render(catalog, record, &opts)?.text)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::assessment::Placement;
use crate::select;
#[test]
fn point_labels_are_pluralized() {
assert_eq!(plural_points(1.0), "1 point");
assert_eq!(plural_points(2.0), "2 points");
assert_eq!(plural_points(1.5), "1.5 points");
fn options_default_to_the_paper_and_withhold_the_key() {
let opts = Options::default();
assert_eq!(opts.variant, Variant::Exam);
assert!(!opts.config.reveal.shows_key());
}
#[test]
fn escaping_protects_typst_syntax() {
assert_eq!(escape("email me @ home"), "email me \\@ home");
assert_eq!(escape("a < b"), "a \\< b");
fn an_explicit_template_beats_the_config() {
let mut opts = Options::default();
opts.config.template = Some(PathBuf::from("from-config.typ"));
assert_eq!(opts.template_path(), Some(Path::new("from-config.typ")));
opts.template = Some(PathBuf::from("from-cli.typ"));
assert_eq!(opts.template_path(), Some(Path::new("from-cli.typ")));
}
#[test]
@@ -452,8 +382,8 @@ mod tests {
let order = select::option_order(&form, "bank::q-1", 4);
let correct_source = 0usize;
let printed_position = order.iter().position(|i| *i == correct_source).unwrap();
let letter = (b'A' + printed_position as u8) as char;
assert!(('A'..='D').contains(&letter));
let letter = LetterStyle::Upper.label(printed_position);
assert!(["A", "B", "C", "D"].contains(&letter.as_str()));
// And it is reproducible.
let again = select::option_order(&form, "bank::q-1", 4);
assert_eq!(order, again);