docs: mermaid diagram for pipeline (#67)

crates/stages/Cargo.toml

@@ -15,6 +15,7 @@ thiserror = "1.0.37"
 tracing = "0.1.36"
 tracing-futures = "0.2.5"
 tokio = { version = "1.21.2", features = ["sync"] }
+aquamarine = "0.1.12"
 
 [dev-dependencies]
 tokio = { version = "*", features = ["rt", "sync", "macros"] }

crates/stages/src/pipeline.rs

@@ -17,6 +17,7 @@ use ctrl::*;
 pub use event::*;
 use state::*;
 
+#[cfg_attr(doc, aquamarine::aquamarine)]
 /// A staged sync pipeline.
 ///
 /// The pipeline executes queued [stages][Stage] serially. An external component determines the tip
@@ -27,6 +28,40 @@ use state::*;
 /// After the entire pipeline has been run, it will run again unless asked to stop (see
 /// [Pipeline::set_max_block]).
 ///
+/// ```mermaid
+/// graph TB
+///   Start[Start]
+///   Done[Done]
+///   Error[Error]
+///   subgraph Unwind
+///     StartUnwind(Unwind by unwind priority)
+///     UnwindStage(Unwind stage)
+///     NextStageToUnwind(Next stage)
+///   end
+///   subgraph Single loop
+///     RunLoop(Run loop)
+///     NextStage(Next stage)
+///     LoopDone(Loop done)
+///     subgraph Stage Execution
+///       Execute(Execute stage)
+///     end
+///   end
+///   Start --> RunLoop --> NextStage
+///   NextStage --> |No stages left| LoopDone
+///   NextStage --> |Next stage| Execute
+///   Execute --> |Not done| Execute
+///   Execute --> |Unwind requested| StartUnwind
+///   Execute --> |Done| NextStage
+///   Execute --> |Error| Error
+///   StartUnwind --> NextStageToUnwind
+///   NextStageToUnwind --> |Next stage| UnwindStage
+///   NextStageToUnwind --> |No stages left| RunLoop
+///   UnwindStage --> |Error| Error
+///   UnwindStage --> |Unwound| NextStageToUnwind
+///   LoopDone --> |Target block reached| Done
+///   LoopDone --> |Target block not reached| RunLoop
+/// ```
+///
 /// # Unwinding
 ///
 /// In case of a validation error (as determined by the consensus engine) in one of the stages, the

crates/stages/src/pipeline/event.rs

@@ -4,7 +4,7 @@ use crate::{
 };
 use reth_primitives::BlockNumber;
 
-/// An event emitted by a [Pipeline].
+/// An event emitted by a [Pipeline][crate::Pipeline].
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum PipelineEvent {
     /// Emitted when a stage is about to be run.