67 lines
2.9 KiB
Rust
67 lines
2.9 KiB
Rust
// SPDX-License-Identifier: Prosperity-3.0.0
|
|
// Copyright Scientific Computing Studio
|
|
// 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 {}
|