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.
Savjet
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
Konfiguracija¶
To add Gaphor diagram support to Sphinx, make sure Gaphor is listed as a dependency.
Važno
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.
Napomena
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.
Greške¶
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:
Greška
No diagram ‘Wrong name’ in model ‘example’ (../examples/sequence-diagram.gaphor).