sphinx-diagrams

This is a rough (incomplete, but working) Sphinx extension for
Diagrams. Please refer to the open
issue for Sphinx support for
the latest up-to-date version when officially supported.

Usage

Install

$ pip3 install sphinx-diagrams

Adding the extension

conf.py

extensions = [
    "sphinx_diagrams",
]

Adding the diagram (inline)

The simplest way is to use SphinxDiagram and inline the code in your document.
Consider using an external diagram/python script (see below) as it has much
shorter iteration loop than running sphinx and most likely better supported by
your editor or IDE.

source/index.rst

Diagram - Deployment
====================
.. diagrams::
  from diagrams import Cluster
  from diagrams.k8s.compute import Deployment
  from sphinx_diagrams import SphinxDiagram
  with SphinxDiagram(title="GKE"):
      with Cluster("GCP Project"):
          KubernetesEngine("Primary Cluster")

Adding a diagram (external python code)

Write the code

source/diagrams_infrastructure.py

You can still use SphinxDiagram in your own code. This class handles arguments
like and visibility (showing the diagram via xdg-open/open) for
you.

from diagrams import Cluster
from diagrams.k8s.compute import Deployment
from sphinx_diagrams import SphinxDiagram
with SphinxDiagram(title="GKE"):
    with Cluster("GCP Project"):
        KubernetesEngine("Primary Cluster")

Alternatively, you can use Diagram (from diagrams) directly. Note that the
extension will pass two arguments to your diagram script. The first one is the
filename as sys.argv[1] it expects (it needs to match the one outputted by
diagrams) and the value false as sys.argv[2]. The later can be used to
tell your script not to show (open) the generate diagram.

import sys
from diagrams import Diagram, Cluster
from diagrams.gcp.compute import KubernetesEngine
with Diagram("GKE", filename=sys.argv[1], show=sys.argv[2].lower() == 'true'):
    with Cluster("GCP Project"):
        KubernetesEngine("Primary Cluster")

Referencing the diagram

source/index.rst

Diagram - Deployment
====================
.. diagrams:: diagrams_infrastructure.py
  :filename: diagram-deployment.png

If using SphinxDiagram (above) or if the filename of the diagram script is the
same as the output file (e.g.: diagrams_infrastructure.py => diagrams_infrastructure.png) then the is not necessary.

Diagram - Deployment
====================
.. diagrams:: diagrams_infrastructure.py

Credit

This code is based on
sphinx.graphviz.

SPDX-License-Identifier: BSD-2-Clause