mermaid
Version:
Markdownish syntax for generating flowcharts, sequence diagrams and gantt charts.
230 lines (209 loc) • 14.2 kB
HTML
<html>
<head>
<title>development.md</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link rel="stylesheet" media="all" href="../doc-style.css" />
<script src="../doc-filelist.js"></script>
<script>
var relativeDir = "../", thisFile = "Users/knut/Documents/source/mermaid/docs/development.md", defaultSidebar = true;
</script>
<script src="../doc-script.js"></script>
<script src="../mermaid.js"></script>
<link rel="stylesheet" href="../mermaid.css" />
</head>
<body>
<div id="sidebar_wrapper">
<div id="sidebar_switch">
<span class="tree">Files</span>
<span class="headings">Headings</span>
</div>
<div id="tree"></div>
<div id="headings">
<div class="heading h1">
<a href="#Development: Updating the documentation">Development: Updating the documentation</a>
</div>
<div class="heading h2">
<a href="#Getting the development environment up">Getting the development environment up</a>
</div>
<div class="heading h2">
<a href="#Working with the documentation">Working with the documentation</a>
</div>
<div class="heading h2">
<a href="#Committing the changes">Committing the changes</a>
</div>
<div class="heading h1">
<a href="#Things to be done in order to add a new diagram type">Things to be done in order to add a new diagram type</a>
</div>
<div class="heading h2">
<a href="#Step 1: Grammar & Parsing">Step 1: Grammar & Parsing</a>
</div>
<div class="heading h3">
<a href="#Grammar">Grammar</a>
</div>
<div class="heading h3">
<a href="#Store data found during parsing">Store data found during parsing</a>
</div>
<div class="heading h2">
<a href="#Step 2: Rendering">Step 2: Rendering</a>
</div>
<div class="heading h2">
<a href="#Step 3: Detection of the new diagram type">Step 3: Detection of the new diagram type</a>
</div>
<div class="heading h2">
<a href="#Step 4: The final piece - triggering the rendering">Step 4: The final piece - triggering the rendering</a>
</div>
<div class="heading h1">
<a href="#Usage of the parser as a separate module">Usage of the parser as a separate module</a>
</div>
<div class="heading h2">
<a href="#Setup">Setup</a>
</div>
<div class="heading h2">
<a href="#Parsing">Parsing</a>
</div>
<div class="heading h2">
<a href="#Data extraction">Data extraction</a>
</div>
</div>
</div>
<div id="sidebar-toggle"></div>
<div id="container"><div class="docs markdown"><div class="pilwrap" id="Development: Updating the documentation">
<h1>
<a href="#Development: Updating the documentation" name="Development: Updating the documentation" class="pilcrow">¶</a>
Development: Updating the documentation</h1>
</div>
<div class="pilwrap" id="Getting the development environment up">
<h2>
<a href="#Getting the development environment up" name="Getting the development environment up" class="pilcrow">¶</a>
Getting the development environment up</h2>
</div>
<ol>
<li>Fork the gh-pages branch in the the mermaid repository</li>
<li>Do npm install</li>
</ol>
<div class="pilwrap" id="Working with the documentation">
<h2>
<a href="#Working with the documentation" name="Working with the documentation" class="pilcrow">¶</a>
Working with the documentation</h2>
</div>
<p>The html files are generated from the source and the markdown files in the docs folder. The site generation is done
using the docker.js framework with the command below.</p>
<div class="highlight"><pre><code><span class="nx">docker</span> <span class="o">-</span><span class="nx">i</span> <span class="p">..</span><span class="o">/</span><span class="nx">mermaid</span><span class="o">/</span> <span class="o">-</span><span class="nx">x</span> <span class="o">*</span><span class="nx">git</span><span class="o">*|*</span><span class="nx">travis</span><span class="o">*|*</span><span class="nx">bin</span><span class="o">*|*</span><span class="nx">dist</span><span class="o">*|*</span><span class="nx">node_modules</span><span class="o">*|*</span><span class="nx">gulp</span><span class="o">*|*</span><span class="nx">lib</span><span class="o">*|*</span><span class="nx">editor</span><span class="o">*|*</span><span class="nx">conf</span><span class="o">*|*</span><span class="nx">scripts</span><span class="o">*|*</span><span class="nx">test</span><span class="o">*|*</span><span class="nx">htmlDocs</span><span class="o">*</span> <span class="o">--</span><span class="nx">extras</span> <span class="nx">mermaid</span> <span class="o">-</span><span class="nx">w</span> <span class="o">-</span><span class="nx">o</span> <span class="nx">htmlDocs</span>
</code></pre></div>
<p>Thus ... One important thing to remember. <em> Do not edit the html files directly! </em> Those changes will be overwritten
when the site is re-generated.</p>
<div class="pilwrap" id="Committing the changes">
<h2>
<a href="#Committing the changes" name="Committing the changes" class="pilcrow">¶</a>
Committing the changes</h2>
</div>
<p>Do a pull request to merge the changes to the site.</p>
<div class="pilwrap" id="Things to be done in order to add a new diagram type">
<h1>
<a href="#Things to be done in order to add a new diagram type" name="Things to be done in order to add a new diagram type" class="pilcrow">¶</a>
Things to be done in order to add a new diagram type</h1>
</div>
<div class="pilwrap" id="Step 1: Grammar & Parsing">
<h2>
<a href="#Step 1: Grammar & Parsing" name="Step 1: Grammar & Parsing" class="pilcrow">¶</a>
Step 1: Grammar & Parsing</h2>
</div>
<div class="pilwrap" id="Grammar">
<h3>
<a href="#Grammar" name="Grammar" class="pilcrow">¶</a>
Grammar</h3>
</div>
<p>This would be to define a jison grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2.</p>
<p>For instance:</p>
<ul>
<li>the flowchart starts with the keyword graph.</li>
<li>the sequence diagram starts with the keyword sequenceDiagram</li>
</ul>
<div class="pilwrap" id="Store data found during parsing">
<h3>
<a href="#Store data found during parsing" name="Store data found during parsing" class="pilcrow">¶</a>
Store data found during parsing</h3>
</div>
<p>There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call a object provided to the parser by the user of the parser. This object can be called during parsing for storing data.</p>
<div class="highlight"><pre><code><span class="nx">statement</span>
<span class="o">:</span> <span class="s1">'participant'</span> <span class="nx">actor</span> <span class="p">{</span> <span class="nx">$</span><span class="o">=</span><span class="s1">'actor'</span><span class="p">;</span> <span class="p">}</span>
<span class="o">|</span> <span class="nx">signal</span> <span class="p">{</span> <span class="nx">$</span><span class="o">=</span><span class="s1">'signal'</span><span class="p">;</span> <span class="p">}</span>
<span class="o">|</span> <span class="nx">note_statement</span> <span class="p">{</span> <span class="nx">$</span><span class="o">=</span><span class="s1">'note'</span><span class="p">;</span> <span class="p">}</span>
<span class="o">|</span> <span class="s1">'title'</span> <span class="nx">message</span> <span class="p">{</span> <span class="nx">yy</span><span class="p">.</span><span class="nx">setTitle</span><span class="p">(</span><span class="nx">$2</span><span class="p">);</span> <span class="p">}</span>
<span class="p">;</span>
</code></pre></div>
<p>In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered.</p>
<p><strong>Note:</strong> Make sure that the parseError function for the parser is defined and calling mermaidPAI.parseError this way a common way of detecting parse errors is provided for the end-user.</p>
<p>For more info look in the example diagram type:</p>
<p>The yy object has the following function:</p>
<div class="highlight"><pre><code><span class="nx">exports</span><span class="p">.</span><span class="nx">parseError</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">err</span><span class="p">,</span><span class="nx">hash</span><span class="p">){</span>
<span class="nx">mermaidAPI</span><span class="p">.</span><span class="nx">parseError</span><span class="p">(</span><span class="nx">err</span><span class="p">,</span><span class="nx">hash</span><span class="p">);</span>
<span class="p">};</span>
</code></pre></div>
<p>when parsing the yy object is initialized as per below:</p>
<div class="highlight"><pre><code> <span class="kd">var</span> <span class="nx">parser</span><span class="p">;</span>
<span class="nx">parser</span> <span class="o">=</span> <span class="nx">exampleParser</span><span class="p">.</span><span class="nx">parser</span><span class="p">;</span>
<span class="nx">parser</span><span class="p">.</span><span class="nx">yy</span> <span class="o">=</span> <span class="nx">db</span><span class="p">;</span>
</code></pre></div>
<div class="pilwrap" id="Step 2: Rendering">
<h2>
<a href="#Step 2: Rendering" name="Step 2: Rendering" class="pilcrow">¶</a>
Step 2: Rendering</h2>
</div>
<p>Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequendeRenderer.js rather then the flowchart renderer as this is a more generic example.</p>
<p>Place the renderer in the diagram folder.</p>
<div class="pilwrap" id="Step 3: Detection of the new diagram type">
<h2>
<a href="#Step 3: Detection of the new diagram type" name="Step 3: Detection of the new diagram type" class="pilcrow">¶</a>
Step 3: Detection of the new diagram type</h2>
</div>
<p>The second thing to do is to add the capability to detect the new new diagram to type to the detectType in utils.js. The detection should return a key for the new diagram type.</p>
<div class="pilwrap" id="Step 4: The final piece - triggering the rendering">
<h2>
<a href="#Step 4: The final piece - triggering the rendering" name="Step 4: The final piece - triggering the rendering" class="pilcrow">¶</a>
Step 4: The final piece - triggering the rendering</h2>
</div>
<p>At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step number 2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument.</p>
<div class="pilwrap" id="Usage of the parser as a separate module">
<h1>
<a href="#Usage of the parser as a separate module" name="Usage of the parser as a separate module" class="pilcrow">¶</a>
Usage of the parser as a separate module</h1>
</div>
<div class="pilwrap" id="Setup">
<h2>
<a href="#Setup" name="Setup" class="pilcrow">¶</a>
Setup</h2>
</div>
<div class="highlight"><pre><code><span class="kd">var</span> <span class="nx">graph</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'./graphDb'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">flow</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'./parser/flow'</span><span class="p">);</span>
<span class="nx">flow</span><span class="p">.</span><span class="nx">parser</span><span class="p">.</span><span class="nx">yy</span> <span class="o">=</span> <span class="nx">graph</span><span class="p">;</span>
</code></pre></div>
<div class="pilwrap" id="Parsing">
<h2>
<a href="#Parsing" name="Parsing" class="pilcrow">¶</a>
Parsing</h2>
</div>
<div class="highlight"><pre><code><span class="nx">flow</span><span class="p">.</span><span class="nx">parser</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span><span class="nx">text</span><span class="p">);</span>
</code></pre></div>
<div class="pilwrap" id="Data extraction">
<h2>
<a href="#Data extraction" name="Data extraction" class="pilcrow">¶</a>
Data extraction</h2>
</div>
<div class="highlight"><pre><code><span class="c1">// Javascript example</span>
<span class="nx">graph</span><span class="p">.</span><span class="nx">getDirection</span><span class="p">();</span>
<span class="nx">graph</span><span class="p">.</span><span class="nx">getVertices</span><span class="p">();</span>
<span class="nx">graph</span><span class="p">.</span><span class="nx">getEdges</span><span class="p">();</span>
</code></pre></div>
<p>The parser is also exposed in the mermaid api by calling:</p>
<div class="highlight"><pre><code><span class="kd">var</span> <span class="nx">parser</span> <span class="o">=</span> <span class="nx">mermaid</span><span class="p">.</span><span class="nx">getParser</span><span class="p">();</span>
</code></pre></div>
<p>Note that the parse needs a graph object to store the data as per:</p>
<div class="highlight"><pre><code><span class="nx">flow</span><span class="p">.</span><span class="nx">parser</span><span class="p">.</span><span class="nx">yy</span> <span class="o">=</span> <span class="nx">graph</span><span class="p">;</span>
</code></pre></div>
<p>Look at graphDb.js for more details on that object.</p>
</div>
</div>
</body>
</html>