mersinvald / aquamarine

Inline diagrams for rustdoc with mermaid.js
MIT License
487 stars 25 forks source link

Docs render wrong #11

Closed jmg-duarte closed 3 years ago

jmg-duarte commented 3 years ago

Hello!

First of all, amazing crate being able to embed diagrams in the documentation is great!

I'm currently building an embedded DSL and part of my functionally is exporting diagrams of several kinds. Logically, embedding them in the documentation would be the next step and hence I started using aquamarine.

During the process I noticed my diagrams were correct according to the Live Editor, but when rendered they would be missing the decision diamond for example.

This is the current renderization:

#[cfg_attr(doc, ::aquamarine::aquamarine)]
#[doc= "```mermaid"]
#[doc= "stateDiagram-v2"]
#[doc= "  [*] --> AccountValidation : start_transaction"]
#[doc= "  Error --> [*] : finish"]
#[doc= "  Finish --> [*] : finish"]
#[doc= "  state C_Valid <<choice>>"]
#[doc= "  Valid --> C_Valid: perform_transaction"]
#[doc= "  C_Valid --> Error"]
#[doc= "  C_Valid --> Finish"]
#[doc= "  state C_AccountValidation <<choice>>"]
#[doc= "  AccountValidation --> C_AccountValidation: validate_accounts"]
#[doc= "  C_AccountValidation --> Error"]
#[doc= "  C_AccountValidation --> Valid"]
#[doc= "```"]
const WEIRD: i32 = 0;

image

I tried upgrading mermaid.js to the newest version and suddenly the diagrams present in main.rs work.

#[cfg_attr(doc, ::aquamarine::aquamarine)]
#[doc= "```mermaid"]
#[doc= "stateDiagram-v2"]
#[doc= "  [*] --> AccountValidation : start_transaction"]
#[doc= "  Error --> [*] : finish"]
#[doc= "  Finish --> [*] : finish"]
#[doc= "  state C_Valid <<choice>>"]
#[doc= "  Valid --> C_Valid: perform_transaction"]
#[doc= "  C_Valid --> Error"]
#[doc= "  C_Valid --> Finish"]
#[doc= "  state C_AccountValidation <<choice>>"]
#[doc= "  AccountValidation --> C_AccountValidation: validate_accounts"]
#[doc= "  C_AccountValidation --> Error"]
#[doc= "  C_AccountValidation --> Valid"]
#[doc= "```"]
const LOGIN: &'static str = "login";

image

But using the current version I get this:

image

If you're wondering why I am using #[doc="..."]:

Any idea what the problem might be? I'd be more than glad to help since this is a valuable feature for my crate but I'd need some guidance.

jmg-duarte commented 3 years ago

On another note, I don't know what the dark circle in the top right is. But I don't know (yet) if it merits an issue.