Feat: Add Mermaid Diagrams

Breakthrough-Energy / docs

Documentation

https://breakthrough-energy.github.io/docs/

Creative Commons Attribution 4.0 International

13 stars 14 forks source link

Feat: Add Mermaid Diagrams #63

Closed ahurli closed 3 years ago

ahurli commented 3 years ago

Purpose

Add mermaid diagrams to the documentation

What the code is doing

Mermaid cli has been added as a sphinx extension, and the dockerfile has been updated to include mermaid in the build. There is a diagram added to the landing page showing the interactions between the different repos.

Testing

Both running tox locally and docker-compose up --build successfully build the expected docs with the embedded diagram.

Time estimate

5 min

kasparm commented 3 years ago

@ahurli would it be possible to point from PreREISE to PowerSimData and PowerSimData to PostREISE (Point from yellow box to yellow box)to avoid the arrows to go over text?

ahurli commented 3 years ago

There seems to be something slightly buggy with the subgraphs (they're a relatively new feature), so I wasn't able to get it with a labeled, dotted arrow, but was able to get something at least without overlap by removing the label and dotting:

danielolsen commented 3 years ago

Shouldn't the .mat and .csv files be labelled on the arrow from Execute to REISE.jl? And shouldn't the pickle files be labelled on an arrow from REISE.jl to Analyze?

ahurli commented 3 years ago

Shouldn't the .mat and .csv files be labelled on the arrow from Execute to REISE.jl? And shouldn't the pickle files be labelled on an arrow from REISE.jl to Analyze?

Yes, I agree that's more accurate, I think the overall diagram looks busier and harder to understand:

Maybe we should leave out the file types out altogether?

danielolsen commented 3 years ago

Maybe it's less crowded if the pkl files are on an arrow from REISE.jl to Analyze, instead of Execute.

rouille commented 3 years ago

Maybe it's less crowded if the pkl files are on an arrow from REISE.jl to Analyze, instead of Execute.

I agree and this is what actually happens since the state is set to analyze (in the ScenarioList) in the extract_data script that is in the pyreisejl directory of REISE.jl.

ahurli commented 3 years ago

This is what it looks like now. Much more spaced out, but I suppose this is the best so far.