Crate simple_mermaid

source ·
Expand description

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.

/// A sequence diagram
#[doc = mermaid!("sequence.mmd")]
///
/// Then a flowchart
#[doc = mermaid!("flowchart.mmd")]
///
/// And some more regular text to end this block

Outputs:

A sequence diagram

sequenceDiagram
    Alice->>Bob: Hello Bob, how are you ?
    Bob->>Alice: Fine, thank you. And you?
    create participant Carl
    Alice->>Carl: Hi Carl!
    create actor D as Donald
    Carl->>D: Hi!
    destroy Carl
    Alice-xCarl: We are too many
    destroy Bob
    Bob->>Alice: I agree



Then a flowchart


flowchart TD
    A[Start] --> B{Is it?}
    B -- Yes --> C[OK]
    C --> D[Rethink]
    D --> B
    B -- No ----> E[End]



And some more regular text to end this block

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.

#[doc = mermaid!("er.mmd" left)]
#[doc = mermaid!("graph.mmd" framed)]
#[doc = mermaid!("timeline.mmd" right)]
#[doc = mermaid!("larger.mmd" center framed)]
erDiagram
    CAR ||--o{ NAMED-DRIVER : allows
    CAR {
        string registrationNumber
        string make
        string model
    }
    PERSON ||--o{ NAMED-DRIVER : is
    PERSON {
        string firstName
        string lastName
        int age
    }

graph TD
    A[Enter Chart Definition] --> B(Preview)
    B --> C{decide}
    C --> D[Keep]
    C --> E[Edit Definition]
    E --> B
    D --> F[Save Image and Code]
    F --> B

timeline
    title Timeline of Industrial Revolution
    section 17th-20th century
        Industry 1.0 : Machinery, Water power, Steam 
power
        Industry 2.0 : Electricity, Internal combustion engine, Mass production
        Industry 3.0 : Electronics, Computers, Automation
    section 21st century
        Industry 4.0 : Internet, Robotics, Internet of Things
        Industry 5.0 : Artificial intelligence, Big data,3D printing

sequenceDiagram
    participant web as Web Browser
    participant blog as Blog Service
    participant account as Account Service
    participant mail as Mail Service
    participant db as Storage

    Note over web,db: The user must be logged in to submit blog posts
    web->>+account: Logs in using credentials
    account->>db: Query stored accounts
    db->>account: Respond with query result

    alt Credentials not found
        account->>web: Invalid credentials
    else Credentials found
        account->>-web: Successfully logged in

        Note over web,db: When the user is authenticated, they can now submit new posts
        web->>+blog: Submit new post
        blog->>db: Store post data

        par Notifications
            blog--)mail: Send mail to blog subscribers
            blog--)db: Store in-site notifications
        and Response
            blog-->>-web: Successfully posted
        end
    end

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.

Macros

  • mermaid
    Include a mermaid diagram in the documentation.