Sphinx Extension

What’s more awesome than to use Gaphor diagrams directly in your Sphinx documentation. Whether you write your docs in reStructured Text or Markdown, we’ve got you covered.


Here we cover the reStructured Text syntax. If you prefer markdown, we suggest you have a look at the MyST-parser, as it supports Sphinx directives.

It requires minimal effort to set up. Adding a diagram is as simple as:

.. diagram:: main

In case you use multiple Gaphor source files, you need to define a :model: attribute and add the model names to the Sphinx configuration file (conf.py).

.. diagram:: main
   :model: example

Diagrams can be referenced by their name, or by their fully qualified name.

.. diagram:: New model.main

Image properties can also be applied:

.. diagram:: main
   :width: 50%
   :align: right
   :alt: A description suitable for an example
A description suitable for an example


To add Gaphor diagram support to Sphinx, make sure Gaphor is listed as a dependency.


Gaphor requires at least Python 3.9.

Secondly, add the following to your conf.py file:

Step 1: Add gaphor as extension.

extensions = [

Step 2: Add references to models

# A single model
gaphor_models = "../examples/sequence-diagram.gaphor"

# Or multiple models
gaphor_models = {
    "connect": "connect.gaphor",
    "example": "../examples/sequence-diagram.gaphor"

Now include diagram directives in your documents.

Read the Docs

The diagram directive plays nice with Read the docs. To make diagrams render, it’s best to use a .readthedocs.yaml file in your project. Make sure to include the extra apt_packages as shown below.

This is the .readthedocs.yaml file we use for Gaphor:

version: 2
formats: all
  os: ubuntu-22.04
    python: "3.12"
  - libgirepository1.0-dev
  - gir1.2-pango-1.0
  - graphviz
    - pip install --constraint=.github/constraints.txt poetry
    - poetry config virtualenvs.create false
    - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
  configuration: docs/conf.py
  fail_on_warning: true
  • libgirepository1.0-dev is required to build PyGObject.

  • gir1.2-pango-1.0 is required for text rendering.


For Gaphor 2.7.0, gir1.2-gtk-3.0 and gir1.2-gtksource-4 are required apt_packages, although we do not use the GUI. From Gaphor 2.7.1 onwards all you need is GI-repository and Pango.


Errors are shown on the console when the documentation is built and in the document.

An error will appear in the documentation. Something like this:


No diagram ‘Wrong name’ in model ‘example’ (../examples/sequence-diagram.gaphor).