Repository navigation
docs(planner): outline egg-style tutorials in asap-planner - #1305
Merged
Merged
Conversation
Add a doc-only tutorials module with six chapter outlines, each rendered from its own markdown file, and link them from the crate docs.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
asap-planner.tutorialsmodule inasap-planner, laid out like egg's (src/tutorials/mod.rswith one#[doc = include_str!(...)]module per chapter), with six chapter outlines and a "Tutorials" section in the crate docs that links them in order.asap_planner::tutorials::_01_background…_06_extending). This PR is the outline only; the chapter content (with runnable doctests) follows once the Tracking: implement the optimization formulation (memo candidates, properties, edges y_{u,c,i}, MILP) as named code per stage #1207 mainline (refactor(stage3): select over execution contexts: x_{κ,v}, y_{κ,u,c,i}, h_v and constraint (R) (#1207 PR 7) #1237 → refactor(stage3): constraint (K) per execution and metric; sign-conditioned DDSketch guarantee, classic HLL certificate from the source's distinct bound (#1207 PR 8) #1238 → refactor: tools and snapshots over the #1207 memo, edges and contexts (#1207 PR 9) #1239) merges, so the examples use the final interfaces.Review guide
Base:
main. Readcrates/planner/src/tutorials/mod.rs, then the six_0N_*.mdoutlines; thelib.rschange is the "Tutorials" section andpub 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 onmain._01_background_02_planning_a_workloadplan_installable; readingPhysicalASAPDAG,SelectedPlanReport,Selection_03_accuracy_targetsAccuracyTargetbuilder; exact vs sketch_04_deployment_and_costDeploymentCapabilities,CostInputs; one query, different plans_05_executing_a_planasap-executorcompile → instantiate → execute_06_extendingBehavior: before → after
Before:
cargo doc -p asap-planner --openshows 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.rsThe modules are empty; they exist only to carry documentation.
Algorithm changes
None.
Decisions and open questions
None.
Verification
RUSTDOCFLAGS="-D warnings" cargo doc -p asap-planner --no-depscargo test -p asap-planner --doccargo fmt -p asap-planner --checkcargo clippy -p asap-planner --all-targets -- -D warningsTo 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.