Diagrams Overview

One piece generate document workflows allow for the creation of materials containing a wide variety of simple diagrams produced from simple text descriptions contained within the body of the document.

Making changes to the diagram simply requires a change to the original text description of it. When the document is reflowed, the diagram will be directly updated. There is no distance between the source material and the rendered diagram. The source material contains the description of the diagram and rendered directly from it.

By providing learners with tools of production related to diagram generation, we also make it easier for them to create their own diagrams and explore appropriate visual ways of supporting their own learning.

Several package exists that support the generation of diagrams from simple text descriptions of them. Through the creation of simple magics, we can use cell block magic to configure a code cell to accept these various description types and then render diagrams directly from them.

By including the the textual generator script in the source document, output assets can be generated in situ. Updating or maintaining the images takes place in the context within which the asset is used, minimising opportunities for the asset and the surrounding text context to become disjointed.

The availability of simple text descriptions of a diagram, from which diagrams are typically rendered according to a fixed convention (although layout algorithms may determine the specific location of diagram components within a particular diagram) might also be used as mimimally sufficient text description of many key features of the diagram.

Currently, meaningful human readable “long description” text descriptions to support accessibility are not generated from the original generative text descriptions, but the potential is there for such development if the will is there to exploit it.

Several different approaches are possible for generating diagrams, both static and interactive, in a Jupyter Book publishing workflow from diagram source scripts:

  • using Python packages that render output diagrams as code cell outputs;

  • using magics to parse diagram scripts and generate output diagrams;

  • using hybrid approaches, for example magicked diagram script cells to generate output cells in a live interactive notebook or a Sphinx/Jupyter Book plugin to render the generated diagram in the output document from a code cell script.

In this chapter, we will review the use of magics and also explore how these might integrate with a diagram rendering workflow provided by the Sphinx/Jupyter Book publishing workflow.

Depending on the editor or environment being used to render to the diagram, the same generator script can be used to generate diagrams in different contexts.

Mermaid.js diagram specified in IPython block magic code cell:

%%mermaid_magic

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Output is rendered as cell output when code cell is run.

Mermaid.js diagram specified in MyST labeled code fenced block in a Markdown cell:

```{mermaid}
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Output is rendered in Sphinx generated output document.

Mermaid.js diagram specified with VS Code Makrdown Preview Enhanced detected code fence label in a Markdown cell:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Output is previewed in live preview window (when editing Markdown document).

Ideally, it would make more sense to be able to tag a cell (for example, a raw code cell) with a particular tag (render-mermaid) and then just include the raw script in the cell, allowing the UI or processing engine to decide how best to render or preview the generated diagram.