tididi/
guide.rs

1// scenario: docs/scenarios.md#reading-order
2
3//! The [API overview](api) groups circuit operations and links to their specifications.
4//! The [worked examples](examples) combine these operations in applications.
5//! Read the [data model](model) for the representation or the
6//! [architecture reference](architecture) for the implementation.
7
8// Keep the index, sidebar and module declarations in one reading order.
9macro_rules! walkthroughs {
10    ($($name:ident => ($title:literal, $description:literal)),+ $(,)?) => {
11        macro_rules! navigation {
12            () => {
13                concat!(
14                    "<script>(() => { const examples = [",
15                    $("[\"", stringify!($name), "\",\"", $title, "\"],",)+
16                    "];", include_str!("../docs/example-navigation.js"), "})();</script>"
17                )
18            };
19        }
20
21        #[doc = concat!(
22            "Worked examples, from basic circuit operations to custom calculations.\n\n",
23            $("1. [", $title, "](examples::", stringify!($name), ") — ", $description, "\n",)+
24        )]
25        #[doc = navigation!()]
26        pub mod examples {
27            $(
28                #[doc = include_str!(concat!("../docs/examples/", stringify!($name), ".md"))]
29                // Only excerpts checked against runnable programs suppress the badge.
30                #[doc = "<style>.example-wrap.ignore:has(> pre.tested-example) > .tooltip { display: none; }</style>"]
31                #[doc = navigation!()]
32                pub mod $name {}
33            )+
34        }
35    };
36}
37
38walkthroughs! {
39    configurations => ("Configurations", "Build rules, count solutions, and update a user's choices."),
40    counting => ("What are we counting?", "Distinguish observations, substitution, and projection."),
41    probability => ("Probabilities", "Evaluate events under changing probabilities."),
42    reachability => ("Reachability", "Explore the states reachable through a transition system."),
43    tables => ("Tables and updates", "Build a circuit from rows and maintain it as the table changes."),
44    persistence => ("Saving and loading", "Save circuits and restore them for later use."),
45    vtrees => ("Variable grouping", "Compare circuit sizes under different vtrees."),
46    composition => ("Reusable components", "Place a compiled circuit in a larger model and connect its copies."),
47    care => ("Simplify under assumptions", "Reduce a circuit where a care set is guaranteed to hold."),
48    execution => ("Execution limits", "Bound work and release retained scratch buffers."),
49    optimization => ("Minimum costs", "Define a custom evaluation algebra."),
50    marginalization => ("Keep values instead of structure", "Preserve counts or fixed weighted values while discarding a subtree."),
51    statistics => ("Circuit statistics", "Traverse nodes and pairs for a custom measurement."),
52}
53
54#[doc = include_str!("../docs/api-guide.md")]
55pub mod api {}
56
57#[doc = include_str!("../docs/tdd.md")]
58pub mod model {}
59
60#[doc = include_str!("../docs/architecture.md")]
61pub mod architecture {}
tididi/guide.rs

tididi/
guide.rs
