Sphinx / Jupyter Book Diagramming Plugins

Several Sphinx plugins exist that can be used to generate diagrams from simple text descriptions wrapped in appropriately labeled fenced code blocks.

For example:

In many cases, Jupyter notebook extensions also exist that provide magics that can render equivalent scripts in block magicked cells to render corresponding diagrams as part of the magicked cell output.

After installing the packages from PyPi, these extensions are enabled in a Jupyter Book workflow by adding the following sort of configuration data to the _config.yml file:

sphinx:
  extra_extensions:
    - sphinxcontrib.mermaid
    - sphinxcontrib.wavedrom
    - sphinxcontrib.plantuml
    - sphinxcontrib.tikz
    - sphinxcontrib.blockdiag

On inspection of the source document, the following diagram (as rendered by Jupyter Book) is actually a markdown cell containing a {mermaid} labeled fenced code block and appropriate diagram source script:

flowchart LR .ipynb --jupytext--> .md--> id1{{process Markdown}}--jupytext--> ipynb2[.ipynb]

On inspection of the source document, the following diagram (as rendered by Jupyter Book) is actually a markdown cell containing a {wavedrom} labeled fenced code block and appropriate diagram source script:

On inspection of the source document, the following diagram (as rendered by Jupyter Book) is actually a markdown cell containing a {uml} (PlantUML) labeled fenced code block and appropriate diagram source script:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

On inspection of the source document, the following diagram (as rendered by Jupyter Book) is actually a markdown cell containing a {tikz} labeled fenced code block and appropriate diagram source script:

Figure made with TikZ

On inspection of the source document, the following diagram (as rendered by Jupyter Book) is actually a markdown cell containing a {blockdiag} labeled fenced code block and appropriate diagram source script: