1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
//! Simple Mermaid diagrams RustDoc integration
//!
//! This crate provides a simple declarative macro to include [mermaid] diagrams in your rustdoc documentation.
//! Lookup the great [mermaid documentation] for details on the diagram syntax.
//!
//! # Usage
//! 1. Create your [mermaid] diagrams in their own files (usually with `.mmd` or `.mermaid` extension).
//! 2. Call the [mermaid!] macro in a `#[doc]` attribute. Specify the route to the diagram file as a
//! string literal. Note that the path is interpreted relative to the file where the macro is called,
//! as it happens with the underlying [include_str].
//! 3. Done!
//!
//! Diagrams can be intermixed freely with regular documentation comments.
//!
//! ```rust
//! # use simple_mermaid::mermaid;
//! /// A sequence diagram
//! #[doc = mermaid!("sequence.mmd")]
//! ///
//! /// Then a flowchart
//! #[doc = mermaid!("flowchart.mmd")]
//! ///
//! /// And some more regular text to end this block
//! # fn function() {}
//! ```
//! Outputs:
//!
//! <pre>
//! A sequence diagram
//! Then a flowchart
//! And some more regular text to end this block
//! </pre>
//!
//! # Options
//! By default, diagrams will be centered and have a transparent background. This behaviour can be
//! controlled with the following keywords after the path to the [mermaid] file:
//!
//! * **left**, left align the diagram.
//! * **right**, right align the diagram.
//! * **center**, has not effect, but it\"s accepted for completeness.
//! * **framed**, add a gray frame to the diagram.
//! * **transparent**, do not add the gray frame to the diagram.
//!
//! *Left*, *center* and *right* are, of course, mutually exclusive; but either can be combined with *framed*.
//!
//! ```rust
//! # use simple_mermaid::mermaid;
//! #[doc = mermaid!("er.mmd" left)]
//! #[doc = mermaid!("graph.mmd" framed)]
//! #[doc = mermaid!("timeline.mmd" right)]
//! #[doc = mermaid!("larger.mmd" center framed)]
//! # fn function() {}
//! ```
//!
//! # Alternatives
//! ## aquamarine
//! The [aquamarine] introduces a procedural macro that converts regular code blocks marked with the
//! [mermaid] language tag. It also allows including the diagram from external files, but that comes with some limitations:
//! * Only one external diagram can be added to a single doc block.
//! * The external diagram will always appear at the end of the doc block.
//!
//! Those limitations made [aquamarine] a non-option for me, since I strongly prefer leaving the diagrams in external files for several reasons:
//! clutter, maintainability, IDE support, and, re-usability of the diagrams.
//!
//! Besides, the declarative macro used in this crate should be easier on compile times. And it comes with no dependencies at all!
//!
//! ## rsdoc
//! The [rsdoc] crate provides procedural macros to embed [PlantUML] and images in doc coments.
//! It can be used with code-blocks (similar to aquamarine) or with external files (similar to this crate).
//! So, in this case, for me it was just a matter of personal taste, both [PlantUML] and [mermaid] are fantastic
//! opensource projects. But PlantUML is Java... and my plants always die (_even a cactus I once had! How can a cactus die? The thing should not need water!_).
//!
//! # Disclaimer
//! Neither this crate nor it's autor have any relation or affiliation with the [mermaid] project, other that being an user of this magnific library.
//!
//! All the examples in this documentation have been extracted, verbatim or with minor updates, from the [mermaid documentation].
//!
//! [mermaid]: https://mermaid.js.org/
//! [include_str]: https://doc.rust-lang.org/std/macro.include_str.html
//! [mermaid documentation]: https://mermaid.js.org/intro/n00b-gettingStarted.html
//! [aquamarine]: https://crates.io/crates/aquamarine
//! [rsdoc]: https://crates.io/crates/rsdoc
//! [PlantUML]: https://plantuml.com/
/// Include a mermaid diagram in the documentation.
///
/// This macro is meant to be used as argument of the `#[doc]` attribute.
///
/// ```rust
/// # use simple_mermaid::mermaid;
/// /// Some documentation about a function
/// /// Then include a diagram:
/// #[doc = mermaid!("netflix.mmd")]
/// fn a_function() {}
/// ```
///
/// This would produce:
///
/// > Some documentation
/// >
/// > Then include a diagram:
///
/// Look at the crate level documentation for all the options.