Skip to content

docs(planner): outline egg-style tutorials in asap-planner - #1305

Merged
zzylol merged 2 commits into
mainfrom
docs/planner-tutorials-outline
Nov 14, 2026
Merged

zzylol merged 2 commits into
mainfrom
docs/planner-tutorials-outline

Conversation

@zzylol

@zzylol zzylol commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Review guide

Base: main. Read crates/planner/src/tutorials/mod.rs, then the six _0N_*.md outlines; the lib.rs change is the "Tutorials" section and pub mod tutorials;. Check that each outline covers the right things and that the chapter order makes sense. Every type and function named in the outlines was checked against the code on main.

Chapter Teaches For
_01_background repeated monitoring queries, sketches, materialization; memo group, candidate, plan newcomers
_02_planning_a_workload PromQL query + data workload → plan_installable; reading PhysicalASAPDAG, SelectedPlanReport, Selection library users
_03_accuracy_targets AccuracyTarget builder; exact vs sketch library users
_04_deployment_and_cost DeploymentCapabilities, CostInputs; one query, different plans integrators
_05_executing_a_plan asap-executor compile → instantiate → execute runtime developers
_06_extending adding a sketch family or a reuse rule contributors

Behavior: before → after

Before: cargo doc -p asap-planner --open shows only the API. After: the crate page has a "Tutorials" section linking six chapter pages, each saying it is an outline and listing its sections. No code changes.

Interfaces

crates/planner/src/tutorials/mod.rs

+/// Doc-only: the guide-level tutorials, one module per chapter.
+pub mod tutorials {
+    pub mod _01_background {}
+    pub mod _02_planning_a_workload {}
+    pub mod _03_accuracy_targets {}
+    pub mod _04_deployment_and_cost {}
+    pub mod _05_executing_a_plan {}
+    pub mod _06_extending {}
+}

The modules are empty; they exist only to carry documentation.

Algorithm changes

None.

Decisions and open questions

None.

Verification

Scope Result Notes
RUSTDOCFLAGS="-D warnings" cargo doc -p asap-planner --no-deps passed all intra-doc links resolve
cargo test -p asap-planner --doc passed (0 doctests) outlines have no code blocks yet
cargo fmt -p asap-planner --check passed
cargo clippy -p asap-planner --all-targets -- -D warnings passed

To view: cargo doc -p asap-planner --no-deps --open, then follow "Tutorials" on the crate page.

Follow-ups

Write the chapter content, with runnable doctests, after the #1207 mainline (#1237 → #1238 → #1239) merges.

Add a doc-only tutorials module with six chapter outlines, each rendered
from its own markdown file, and link them from the crate docs.
@zzylol zzylol added the documentation Improvements or additions to documentation label Nov 14, 2026
Cost model 1 only in plan selection; failures via NoValidCandidate and
pruned candidates via Selection::pruned_candidates; candidates pruned
with a recorded reason; scalar_roots and Option cost in the plan report;
a plan covers the groups the queries need.
@zzylol
zzylol merged commit 09a1a2d into main Nov 14, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant