Diagrams as code#
Rubin user guides use Mermaid (through sphinxcontrib-mermaid) for diagrams-as-code. With Mermaid, you can express common diagram types like flow charts, sequence diagrams, and entity relationship diagrams with plain text source code. The diagrams on rendered dynamically, within the web client. Mermaid makes diagrams more maintainable since you don’t need to manage proprietary graphics formats and binary files.
Diagrams can be embedded directly in the page’s source with the
.. mermaid:: flowchart LR rsp(Rubin Science Platform) rsp --> p(Portal) rsp --> n(Notebooks) rsp --> a(APIs) p --> a n --> a
```mermaid flowchart LR rsp(Rubin Science Platform) rsp --> p(Portal) rsp --> n(Notebooks) rsp --> a(APIs) p --> a n --> a ```
Diagrams in separate files#
You can create Mermaid diagrams in separate source files and reference them as arguments to the
.. mermaid:: diagram.mmd
```mermaid diagram.mmd ```
This approach is great for complex diagrams, especially since some editors provide syntax highlighting and live preview for Mermaid diagrams.
Mermaid diagram types#
Mermaid supports many diagram types, including:
See the Mermaid documentation for details on the available diagram types and their syntax.
Diagrams for architectural diagrams#
Mermaid does not have support for architectural diagrams (that is, diagrams showing the infrastructure and services in a deployment). For this application the Diagrams package, with the sphinx-diagrams extension, is ideal.
Installation and set up#
sphinx-diagrams is not part of the standard Documenteer configuration for Rubin user guides. You’ll need to install and configure it:
sphinx-diagramsPython dependency to your project’s development/documentation requirements.
graphvizis available in the build environment. If you are using GitHub Actions with an Ubuntu runner, this can be done with an apt installation:
- name: Install graphviz run: | sudo apt-get install -y graphviz
If you are using tox, you may need to add
graphvizto the documentation environment’s
"sphinx_diagrams"to the extensions list in documenteer.toml:
[sphinx] extensions = [ "sphinx_diagrams" ]
You add Diagrams-based diagrams to your documentation with
As with Mermaid, you can write Diagrams code both within the
diagrams directive, or set the name (or path) of a Python file as an argument to the
Referencing a Python module is recommended to take advantage of syntax highlighting in your code editor.
.. diagrams:: diagram.py
```diagrams diagram.py ```