Skip to main content

Rendering Diagrams in Sphinx

Project description

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 :filename: 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 :filename: is not necessary.

Diagram - Deployment
====================

.. diagrams:: diagrams_infrastructure.py

Credit

This code is based on sphinx.graphviz.

SPDX-License-Identifier: BSD-2-Clause

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinx-diagrams, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size sphinx_diagrams-0.4.0-py3-none-any.whl (6.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size sphinx-diagrams-0.4.0.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page