Crate aquamarine

Expand description

Aquamarine is a procedural macro extension for rustdoc, that aims to improve the visual component of Rust documentation through use of the mermaid.js diagrams.

#[aquamarine] macro works through embedding the mermaid.js into the generated rustdoc HTML page, modifying the doc comment attributes.

To inline a diagram into the documentation, use the mermaid snippet in a doc-string:

#[cfg_attr(doc, aquamarine)]
/// ```mermaid
/// graph LR
///     s([Source]) --> a[[aquamarine]]
///     r[[rustdoc]] --> f([Docs w/ Mermaid!])
///     subgraph rustc[Rust Compiler]
///     a -. inject mermaid.js .-> r
///     end
/// ```
pub fn example() {}

The diagram will appear in place of the mermaid code block, preserving all the comments around it.

You can even add multiple diagrams!

To see it in action, go to the demo crate docs.rs page.

§Dark-mode

Aquamarine will automatically select the dark theme as a default, if the current rustdoc theme is either ayu or dark.

You might need to reload the page to redraw the diagrams after changing the theme.

§Custom themes

Theming is supported on per-diagram basis, through the mermaid’s %%init%% attribute.

Note: custom theme will override the default theme

/// ```mermaid
/// %%{init: {
///     'theme': 'base',
///     'themeVariables': {
///            'primaryColor': '#ffcccc',
///            'edgeLabelBackground':'#ccccff',
///            'tertiaryColor': '#fff0f0' }}}%%
/// graph TD
///      A(Diagram needs to be drawn) --> B{Does it have 'init' annotation?}
///      B -->|No| C(Apply default theme)
///      B -->|Yes| D(Apply customized theme)
/// ```

Demo on docs.rs

To learn more, see the Theming Section of the mermaid.js book

§Loading from a file

When describing complex logic, a diagram can get quite big.

To reduce clutter in your doc comments, you can load a diagram from file using the include_mmd! macro-like syntax.

/// Diagram #1
/// include_mmd!("diagram_1.mmd")
///
/// Diagram #2
/// include_mmd!("diagram_2.mmd")