// 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 {}