generate_docs/
generate_docs.rs

1use std::fs;
2use yasm::*;
3
4// Reuse previously defined state machines
5mod door {
6    use yasm::*;
7
8    define_state_machine! {
9        name: DoorStateMachine,
10        states: { Closed, Open, Locked },
11        inputs: { OpenDoor, CloseDoor, Lock, Unlock },
12        initial: Closed,
13        transitions: {
14            Closed + OpenDoor => Open,
15            Open + CloseDoor => Closed,
16            Closed + Lock => Locked,
17            Locked + Unlock => Closed
18        }
19    }
20}
21
22mod order {
23    use yasm::*;
24
25    define_state_machine! {
26        name: OrderStateMachine,
27        states: { Created, Paid, Shipped, Delivered, Cancelled },
28        inputs: { Pay, Ship, Deliver, Cancel, Refund },
29        initial: Created,
30        transitions: {
31            Created + Pay => Paid,
32            Created + Cancel => Cancelled,
33            Paid + Ship => Shipped,
34            Paid + Refund => Cancelled,
35            Shipped + Deliver => Delivered,
36            Shipped + Cancel => Cancelled
37        }
38    }
39}
40
41mod server {
42    use yasm::*;
43
44    define_state_machine! {
45        name: ServerStateMachine,
46        states: { Pending, Active, Sunsetting, Maintenance, Terminated },
47        inputs: { Activate, Deactivate, Maintain, Terminate, _EditDesc, Rollback, MaintenanceSuccess },
48        initial: Pending,
49        transitions: {
50            Pending + Activate => Active,
51            Active + Deactivate => Sunsetting,
52            Sunsetting + Maintain => Maintenance,
53            Sunsetting + Terminate => Terminated,
54            Sunsetting + Rollback => Pending,
55            Maintenance + Terminate => Terminated,
56            Maintenance + MaintenanceSuccess => Pending,
57            Pending + _EditDesc => Pending,
58            Active + _EditDesc => Active,
59            Sunsetting + _EditDesc => Sunsetting,
60            Maintenance + _EditDesc => Maintenance,
61            Terminated + _EditDesc => Terminated,
62        }
63    }
64}
65
66fn main() -> std::io::Result<()> {
67    println!("📚 Generating state machine documentation...\n");
68
69    // Create output directory
70    fs::create_dir_all("examples/docs")?;
71
72    // Generate door state machine documentation
73    generate_door_docs()?;
74
75    // Generate order state machine documentation
76    generate_order_docs()?;
77
78    // Generate server state machine documentation
79    generate_server_docs()?;
80
81    println!("✅ Documentation generation complete! Check the docs/ directory");
82    println!("\nGenerated files:");
83    println!("- examples/docs/door_state_machine.md");
84    println!("- examples/docs/order_state_machine.md");
85    println!("- examples/docs/door_state_machine.mermaid");
86    println!("- examples/docs/order_state_machine.mermaid");
87    println!("- examples/docs/server_state_machine.md");
88    println!("- examples/docs/server_state_machine.mermaid");
89
90    Ok(())
91}
92
93fn generate_door_docs() -> std::io::Result<()> {
94    println!("🚪 Generating door state machine documentation...");
95
96    // Generate Mermaid diagram
97    let mermaid = StateMachineDoc::<door::DoorStateMachine>::generate_mermaid();
98    fs::write("examples/docs/door_state_machine.mermaid", &mermaid)?;
99
100    // Generate complete Markdown documentation
101    let mut doc = String::new();
102    doc.push_str("# Door State Machine\n\n");
103    doc.push_str("This is a simple door state machine that demonstrates basic door operations: opening, closing, and locking.\n\n");
104
105    doc.push_str("## State Diagram\n\n");
106    doc.push_str("```mermaid\n");
107    doc.push_str(&mermaid);
108    doc.push_str("```\n\n");
109
110    doc.push_str("## State Descriptions\n\n");
111    doc.push_str("- **Closed**: Door is closed, can be opened or locked\n");
112    doc.push_str("- **Open**: Door is open, can only be closed\n");
113    doc.push_str("- **Locked**: Door is locked, can only be unlocked\n\n");
114
115    doc.push_str("## Input Descriptions\n\n");
116    doc.push_str("- **OpenDoor**: Open door operation\n");
117    doc.push_str("- **CloseDoor**: Close door operation\n");
118    doc.push_str("- **Lock**: Lock door operation\n");
119    doc.push_str("- **Unlock**: Unlock door operation\n\n");
120
121    doc.push_str(&StateMachineDoc::<door::DoorStateMachine>::generate_transition_table());
122
123    // Add usage examples
124    doc.push_str("\n## Usage Example\n\n");
125    doc.push_str("```rust\n");
126    doc.push_str("use yasm::*;\n\n");
127    doc.push_str("let mut door = StateMachineInstance::<door::DoorStateMachine>::new();\n");
128    doc.push_str("assert_eq!(*door.current_state(), door::State::Closed);\n\n");
129    doc.push_str("// Open door\n");
130    doc.push_str("door.transition(door::Input::OpenDoor).unwrap();\n");
131    doc.push_str("assert_eq!(*door.current_state(), door::State::Open);\n\n");
132    doc.push_str("// Close door\n");
133    doc.push_str("door.transition(door::Input::CloseDoor).unwrap();\n");
134    doc.push_str("assert_eq!(*door.current_state(), door::State::Closed);\n\n");
135    doc.push_str("// Lock door\n");
136    doc.push_str("door.transition(door::Input::Lock).unwrap();\n");
137    doc.push_str("assert_eq!(*door.current_state(), door::State::Locked);\n");
138    doc.push_str("```\n");
139
140    fs::write("examples/docs/door_state_machine.md", doc)?;
141
142    Ok(())
143}
144
145fn generate_order_docs() -> std::io::Result<()> {
146    println!("📦 Generating order state machine documentation...");
147
148    // Generate Mermaid diagram
149    let mermaid = StateMachineDoc::<order::OrderStateMachine>::generate_mermaid();
150    fs::write("examples/docs/order_state_machine.mermaid", &mermaid)?;
151
152    // Generate complete Markdown documentation
153    let mut doc = String::new();
154    doc.push_str("# Order Processing State Machine\n\n");
155    doc.push_str("This is an order processing state machine that demonstrates the complete lifecycle of an e-commerce order.\n\n");
156
157    doc.push_str("## State Diagram\n\n");
158    doc.push_str("```mermaid\n");
159    doc.push_str(&mermaid);
160    doc.push_str("```\n\n");
161
162    doc.push_str("## State Descriptions\n\n");
163    doc.push_str("- **Created**: Order has been created, waiting for payment\n");
164    doc.push_str("- **Paid**: Order has been paid, waiting for shipment\n");
165    doc.push_str("- **Shipped**: Order has been shipped, in transit\n");
166    doc.push_str("- **Delivered**: Order has been delivered, transaction complete\n");
167    doc.push_str("- **Cancelled**: Order has been cancelled\n\n");
168
169    doc.push_str("## Input Descriptions\n\n");
170    doc.push_str("- **Pay**: Pay for the order\n");
171    doc.push_str("- **Ship**: Ship the order\n");
172    doc.push_str("- **Deliver**: Confirm delivery\n");
173    doc.push_str("- **Cancel**: Cancel the order\n");
174    doc.push_str("- **Refund**: Request a refund\n\n");
175
176    doc.push_str(&StateMachineDoc::<order::OrderStateMachine>::generate_transition_table());
177
178    // Add business process descriptions
179    doc.push_str("\n## Business Processes\n\n");
180    doc.push_str("### Normal Flow\n");
181    doc.push_str("1. Order created (Created)\n");
182    doc.push_str("2. User pays (Pay) → Paid\n");
183    doc.push_str("3. Merchant ships (Ship) → Shipped\n");
184    doc.push_str("4. Delivery confirmed (Deliver) → Delivered\n\n");
185
186    doc.push_str("### Cancellation Flow\n");
187    doc.push_str("- Direct cancellation after creation: Created → (Cancel) → Cancelled\n");
188    doc.push_str("- Refund after payment: Paid → (Refund) → Cancelled\n");
189    doc.push_str("- Cancellation after shipping: Shipped → (Cancel) → Cancelled\n\n");
190
191    doc.push_str("## Usage Example\n\n");
192    doc.push_str("```rust\n");
193    doc.push_str("use yasm::*;\n\n");
194    doc.push_str("let mut order = StateMachineInstance::<order::OrderStateMachine>::new();\n\n");
195    doc.push_str("// Normal order flow\n");
196    doc.push_str("order.transition(order::Input::Pay).unwrap();\n");
197    doc.push_str("order.transition(order::Input::Ship).unwrap();\n");
198    doc.push_str("order.transition(order::Input::Deliver).unwrap();\n");
199    doc.push_str("assert_eq!(*order.current_state(), order::State::Delivered);\n");
200    doc.push_str("```\n");
201
202    fs::write("examples/docs/order_state_machine.md", doc)?;
203
204    Ok(())
205}
206
207fn generate_server_docs() -> std::io::Result<()> {
208    println!("👷 Generating server state machine documentation...");
209
210    // Generate Mermaid diagram
211    let mermaid = StateMachineDoc::<server::ServerStateMachine>::generate_mermaid();
212    fs::write("examples/docs/server_state_machine.mermaid", &mermaid)?;
213
214    // Generate complete Markdown documentation
215    let mut doc = String::new();
216    doc.push_str("# Server State Machine\n\n");
217    doc.push_str("This is a comprehensive server state machine that manages the lifecycle of servers (such as workers, services, or infrastructure components).\n\n");
218
219    doc.push_str("## State Diagram\n\n");
220    doc.push_str("```mermaid\n");
221    doc.push_str(&mermaid);
222    doc.push_str("```\n\n");
223
224    doc.push_str("## State Descriptions\n\n");
225    doc.push_str("- **Pending**: Server is created and waiting to be activated\n");
226    doc.push_str("- **Active**: Server is running and serving requests\n");
227    doc.push_str("- **Sunsetting**: Server is being phased out, no new requests accepted\n");
228    doc.push_str("- **Maintenance**: Server is under maintenance, temporarily unavailable\n");
229    doc.push_str("- **Terminated**: Server has been permanently shut down\n\n");
230
231    doc.push_str("## Input Descriptions\n\n");
232    doc.push_str("- **Activate**: Start the resource and make it available\n");
233    doc.push_str("- **Deactivate**: Begin the sunsetting process\n");
234    doc.push_str("- **Maintain**: Put the resource into maintenance mode\n");
235    doc.push_str("- **Terminate**: Permanently shut down the resource\n");
236    doc.push_str(
237        "- **EditDesc**: Add or modify notes about the resource (available in all states)\n",
238    );
239
240    doc.push_str(&StateMachineDoc::<server::ServerStateMachine>::generate_transition_table());
241
242    // Add operational workflows
243    doc.push_str("\n## Operational Workflows\n\n");
244    doc.push_str("### Normal Lifecycle\n");
245    doc.push_str("1. Server created (Pending)\n");
246    doc.push_str("2. Server activated (Activate) → Active\n");
247    doc.push_str("3. Server deactivated (Deactivate) → Sunsetting\n");
248    doc.push_str("4. Server maintenance (Maintain) → Maintenance\n");
249    doc.push_str("5. Server terminated (Terminate) → Terminated\n\n");
250
251    doc.push_str("### Maintenance Workflow\n");
252    doc.push_str("- From Sunsetting: (Maintain) → Maintenance\n");
253    doc.push_str("- From Maintenance: (Terminate) → Terminated\n\n");
254
255    doc.push_str("### Monitoring Operations\n");
256    doc.push_str("- EditDesc operations are available in all states\n");
257    doc.push_str("- These operations don't change the server state\n");
258    doc.push_str("- Useful for operational monitoring and documentation\n\n");
259
260    doc.push_str("## Usage Example\n\n");
261    doc.push_str("```rust\n");
262    doc.push_str("use yasm::*;\n\n");
263    doc.push_str("let mut server = StateMachineInstance::<server::ServerStateMachine>::new();\n");
264    doc.push_str("assert_eq!(*server.current_state(), server::State::Pending);\n\n");
265    doc.push_str("// Activate server\n");
266    doc.push_str("server.transition(server::Input::Activate).unwrap();\n");
267    doc.push_str("assert_eq!(*server.current_state(), server::State::Active);\n\n");
268    doc.push_str("// Add notes while active\n");
269    doc.push_str("server.transition(server::Input::EditDesc).unwrap();\n");
270    doc.push_str("assert_eq!(*server.current_state(), server::State::Active);\n\n");
271    doc.push_str("// Begin sunsetting\n");
272    doc.push_str("server.transition(server::Input::Deactivate).unwrap();\n");
273    doc.push_str("assert_eq!(*server.current_state(), server::State::Sunsetting);\n\n");
274    doc.push_str("// Enter maintenance mode\n");
275    doc.push_str("server.transition(server::Input::Maintain).unwrap();\n");
276    doc.push_str("assert_eq!(*server.current_state(), server::State::Maintenance);\n\n");
277    doc.push_str("// Maintenance successful\n");
278    doc.push_str("server.transition(server::Input::MaintenanceSuccess).unwrap();\n");
279    doc.push_str("assert_eq!(*server.current_state(), server::State::Pending);\n");
280    doc.push_str("```\n");
281
282    fs::write("examples/docs/server_state_machine.md", doc)?;
283
284    Ok(())
285}
generate_docs/generate_docs.rs

generate_docs/
generate_docs.rs
