Extensión Sphinx

Qué es más impresionante que usar diagramas Gaphor directamente en su documentación Sphinx. Si usted escribe sus documentos en reStructured Text o Markdown, le tenemos cubierto.

Truco

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.

Requiere un esfuerzo mínimo para configurar. Añadir un diagrama es tan simple como:

.. diagram:: main

En caso de usar múltiples archivos fuente Gaphor, es necesario definir un atributo :model: y añadir los nombres de los modelos al archivo de configuración de Sphinx (conf.py).

.. diagram:: main
   :model: example

Se puede hacer referencia a los diagramas por su nombre o por su nombre completo.

.. diagram:: New model.main

Figure, and Image properties can also be applied:

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

   You can also add a caption, if you want.

You can also add a caption, if you want.

Configuración

Para añadir soporte de diagramas Gaphor a Sphinx, asegúrese de que Gaphor aparece como dependencia.

Importante

Gaphor requiere al menos Python 3.9.

En segundo lugar, añada lo siguiente a su archivo conf.py:

Paso 1: Añadir gaphor como extensión.

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

Paso 2: Añadir referencias a los modelos

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

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

Ahora incluye las directivas diagram en tus documentos.

Leer la documentación

La directiva de diagramas funciona bien con Read the docs. Para hacer que los diagramas se muestren, es mejor usar un archivo .readthedocs.yaml en tu proyecto. Asegúrate de incluir el extra apt_packages como se muestra a continuación.

Este es el archivo .readthedocs.yaml que utilizamos para 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

• Se requiere libgirepository-2.0-dev para compilar PyGObject.

• Se requiere gir1.2-pango-1.0 para la representación de texto.

Nota

Para Gaphor 2.7.0, gir1.2-gtk-3.0 y gir1.2-gtksource-4 son necesarios apt_packages, aunque no usamos la GUI. Desde Gaphor 2.7.1 en adelante, todo lo que necesita es un repositorio GI y Pango.

Errores

Los errores se muestran en la consola cuando se construye la documentación y en el documento.

Aparecerá un error en la documentación. Algo como esto:

Error

No hay diagrama “Nombre incorrecto” en el modelo “ejemplo” (../examples/sequence-diagram.gaphor).