Extension Sphinx

Quoi de plus génial que d’utiliser les diagrammes Gaphor directement dans votre documentation Sphinx. Que vous écriviez vos documents en reStructured Text ou en Markdown, nous avons tout prévu.

Astuce

Nous abordons ici la syntaxe de reStructured Text. Si vous préférez Markdown, nous vous suggérons de jeter un œil au MyST-parser, car il prend en charge les directives Sphinx.

Il nécessite un effort minimal pour mettre en place. L’ajout d’un diagramme est aussi simple que :

.. diagram:: main

Dans le cas où vous utilisez plusieurs fichiers sources Gaphor, vous devez définir un attribut :model: et ajouter les noms des modèles au fichier de configuration de Sphinx (conf.py).

.. diagram:: main
   :model: example

Les diagrammes peuvent être référencés par leur nom ou par leur nom complet.

.. diagram:: New model.main

Figure, et Image properties (propriétés de l’image) peuvent également être appliquées :

.. diagram:: main
   :figwidth: image
   :align: center
   :alt: A description suitable for an example

   You can also add a caption, if you want.

Vous pouvez également ajouter une légende, si vous le souhaitez.

Configuration

Pour ajouter le support des diagrammes Gaphor à Sphinx, assurez-vous que Gaphor est listé comme une dépendance.

Important

Gaphor nécessite au moins Python 3.9.

Deuxièmement, ajoutez ce qui suit à votre fichier conf.py :

Étape 1 : Ajouter gaphor comme extension.

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

Étape 2 : Ajouter des références aux modèles

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

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

Incluez maintenant les directives diagram dans vos documents.

Lire les documents

La directive diagramme est compatible avec le module Read the docs. Pour rendre les diagrammes, il est préférable d’utiliser un fichier .readthedocs.yaml dans votre projet. Assurez-vous d’inclure l’élément supplémentaire apt_packages, comme indiqué ci-dessous.

C’est le fichier .readthedocs.yaml que nous utilisons pour Gaphor :

version: 2
formats:
- htmlzip
- epub
build:
  os: ubuntu-24.04
  tools:
    python: "3.14"
  apt_packages:
  - libgirepository-2.0-dev
  - libcairo2-dev
  - pkg-config
  - python3-dev
  - gir1.2-pango-1.0
  - graphviz
  jobs:
    pre_install:
    - python3 -m pip install --upgrade pip
    - python3 -m pip install --constraint=.github/github-requirements.txt poetry poetry-plugin-export
    - poetry config virtualenvs.create false
    - poetry export --format=requirements.txt --output=requirements-only-docs.txt --only=docs
    post_install:
    - python -m pip install .
    - python -m pip install -r requirements-only-docs.txt
sphinx:
  configuration: docs/conf.py
  fail_on_warning: true

• libgirepository-2.0-dev est nécessaire pour construire PyGObject.

• gir1.2-pango-1.0 est nécessaire pour le rendu du texte.

Note

Pour Gaphor 2.7.0, gir1.2-gtk-3.0 et gir1.2-gtksource-4 sont nécessaires apt_packages, bien que nous n’utilisions pas l’interface graphique. À partir de Gaphor 2.7.1, tout ce dont vous avez besoin est GI-repository et Pango.

Errors

Les erreurs sont affichées sur la console lors de la création de la documentation et dans le document.

Une erreur apparaîtra dans la documentation. Quelque chose comme ceci :

Erreur

Pas de diagramme “Mauvais nom” dans le modèle “exemple” (../examples/sequence-diagram.gaphor).