Dev (#1)

Reviewed-on: #1

src/guide.rs

@@ -0,0 +1,60 @@
+// 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. [`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 {}
+
+/// Short answers to specific questions.
+#[doc = include_str!("../docs/guide/recipes.md")]
+pub mod recipes {}