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.

Tip

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

Configuration

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

Important

Gaphor requires at least Python 3.9.

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

Step 1: Add gaphor as extension.

extensions = [
    "gaphor.extensions.sphinx",
]

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
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  apt_packages:
  - libgirepository1.0-dev
  - gir1.2-pango-1.0
  - graphviz
  jobs:
    pre_install:
    - pip install --constraint=.github/constraints.txt poetry
    - poetry config virtualenvs.create false
    post_install:
    - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
sphinx:
  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.

Note

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

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:

Error

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