Migrate Diagrams from Graphviz to Mermaid

[CBroz1]

Feature Request

Problem

• pygraphviz has caused problems for windows users in the past, requiring additional documentation

  • 353

  • 1033

• Current diagrams have aspect ratio issues #975
• Communicating about pipelines is often easier when parties can refer to and change graphs on the fly - dot notation is not new-user friendly
• Primary color styling is not consistent with new DataJoint color palette

Requirements

• A well-supported dependency
• Easy to edit for discussions and feedback

Justification

Adding this feature would allow for more interactive diagrams and provide the opportunity to revisit color choices.

Alternative Considerations

I have personally saved diagrams as dot files, edited, and rendered with unflatten or other CLI tools, but I don't think this process is accessible to new users.

Screenshots

This block highlights what's needed to define the colors, shapes and line information currently used. Although not demonstrated here, there is also support for tooltip displays that could provide more detailed table informaiton.

%%{init: {'theme': 'default', 'themeVariables': { 'textColor': '#00a0df'}}}%%
    flowchart TB %% Text color above chosen to reflect mkdocs CSS
    Mouse --> 
    Session ==> Scan %% Thick line
    Scan --> Alignment((Alignment)) --> Segmentation --> Trace((Trace)) --> RF((RF))
    Scan --> Stimulus --> RF --> Field
    SegmentationMethod -.->|&#8226| Segmentation((Segmentation)) %% Circle shape
    %% class list,of,nodes class-name
    class Alignment,Mouse,RF,Scan,Segmentation,SegmentationMethod,Session,Stimulus,Trace all;
    class Mouse,Scan,Session,Stimulus manual;
    class Segmentation,Trace,RF compute;
    class SegmentationMethod lookup;
    class Alignment import;
    class Field part;
    %% classDef class-name option1:var1,option2:var2;
    classDef all stroke:#333; %% Grey stroke around all tables
    classDef manual fill:#060;  %% Green manual tables
    classDef compute fill:#600; %% Red compute tables
    classDef import fill:#006;  %% Blue import tables
    classDef lookup fill:#ddd;  %% Grey lookup tables
    classDef part fill:#FFF;    %% White part tables

Example diagram:

%%{init: {'theme': 'default', 'themeVariables': { 'textColor': '#00a0df'}}}%%
    flowchart TB %% Text color above chosen to reflect mkdocs CSS
    Mouse --> 
    Session ==> Scan %% Thick line
    Scan --> Alignment((Alignment)) --> Segmentation --> Trace((Trace)) --> RF((RF))
    Scan --> Stimulus --> RF --> Field
    SegmentationMethod -.->|&#8226| Segmentation((Segmentation)) %% Circle shape
    %% class list,of,nodes class-name
    class Alignment,Mouse,RF,Scan,Segmentation,SegmentationMethod,Session,Stimulus,Trace all;
    class Mouse,Scan,Session,Stimulus manual;
    class Segmentation,Trace,RF compute;
    class SegmentationMethod lookup;
    class Alignment import;
    class Field part;
    %% classDef class-name option1:var1,option2:var2;
    classDef all stroke:#333; %% Grey stroke around all tables
    classDef manual fill:#060;  %% Green manual tables
    classDef compute fill:#600; %% Red compute tables
    classDef import fill:#006;  %% Blue import tables
    classDef lookup fill:#ddd;  %% Grey lookup tables
    classDef part fill:#FFF;    %% White part tableshttps://mermaid-js.github.io/mermaid/#/flowchart?id=interaction

[dimitri-yatsenko]

I would argue against it. Graphviz is an established and proven library ported to multiple languages with a great amount of academic and theoretic work. Mermaid is a new and immature product at this point. I suggest closing this issue.

[dimitri-yatsenko]

Graphviz and the dot language are the an industry standard 32 years in open-source development, strarting with AT&T Labs Research, with thousands of applications relying on it.