Files
coursebank/src/guide.rs
T
alexmandClaude c8d6f4a5dd
Pipeline / check (pull_request) Successful in 12m21s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
Name Scienting as the copyright holder and contributor
Replace 'Scientific Computing Studio' in the source headers, the Cargo.toml
authors, and the LICENSE contributor line. pixi.toml still has the old
authors line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014zNf4shD4zaCKLucZWPYL9
2026-10-20 00:21:19 -04:00

67 lines
2.9 KiB
Rust

// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! Long-form documentation: setup, authoring, and worked tutorials.
//!
//! Everything in this module is prose. The modules below hold no code, no types,
//! and no runtime cost; each one exists so that a markdown file under `docs/guide/`
//! gets a page in these docs, a slot in the sidebar, and a stable URL that
//! [intra-doc links](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html)
//! elsewhere in the crate can point at.
//!
//! ## Read in this order
//!
//! The sidebar sorts alphabetically, which is not reading order. This is:
//!
//! 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
//! reusing.
//! 3. [`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
//! gated behind a password.
//! 6. [`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
//!
//! Rust examples in these pages are doctests. `cargo test --doc` compiles every
//! one of them against the crate as it currently is, so renaming
//! [`Catalog::require`](crate::catalog::Catalog::require) breaks the documentation
//! build rather than leaving a page that lies. Most examples carry `no_run`,
//! because they want a course directory on disk that a test runner does not have.
//! `no_run` still type-checks, which is where the value is.
//!
//! Shell transcripts get a `console` fence and YAML gets a `yaml` fence, so
//! rustdoc leaves them alone. A fence with no language is Rust as far as rustdoc is
//! concerned, and a `course.yaml` snippet in a bare fence fails the doc build with
//! a parse error pointing at the markdown. `pixi run check-docs` catches that
//! before the compiler has to.
/// Building a course directory, and what each file in it is for.
#[doc = include_str!("../docs/guide/setup.md")]
pub mod setup {}
/// Writing items that are worth keeping.
#[doc = include_str!("../docs/guide/authoring.md")]
pub mod authoring {}
/// One exam from blueprint to student report.
#[doc = include_str!("../docs/guide/first_exam.md")]
pub mod first_exam {}
/// Printed exams: templates, markers, and render configuration.
#[doc = include_str!("../docs/TYPST.md")]
pub mod typst_export {}
/// Publishing an assignment to the website, with solutions gated behind a password.
#[doc = include_str!("../docs/guide/assignment.md")]
pub mod assignment {}
/// Short answers to specific questions.
#[doc = include_str!("../docs/guide/recipes.md")]
pub mod recipes {}