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
_images/88ff97d7-5c0c-11ea-8042-9771210c7122.svg

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

Configuration

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

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-20.04
  tools:
    python: "3.9"
  apt_packages:
  - libgirepository1.0-dev
  - gir1.2-pango-1.0
  - gir1.2-gtk-3.0
  - gir1.2-gtksource-4  
sphinx:
  configuration: docs/conf.py
python:
  install:
  - method: pip
    path: .
    extra_requirements:
    - docs
  • libgirepository1.0-dev is required to build PyGObject.

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

  • gir1.2-gtk-3.0 and gir1.2-gtksource-4 are needed, although we do not use the GUI.

Errors

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

The model cannot be found:

Error

No model file configured for model ‘not-a-model’.

The model can be found, but the diagram cannot be found:

Error

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