Розширення Сфінкса

Що є чудовішим, ніж використовувати діаграми Gaphor безпосередньо у вашій документації Sphinx. Незалежно від того, чи пишете ви свої документи у reStructured Text або Markdown, ми допоможемо вам.

Порада

Тут ми розглянемо синтаксис reStructured Text. Якщо ви віддаєте перевагу розмітці, радимо вам поглянути на MyST-парсер, оскільки він підтримує директиви Sphinx <https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html>`_.

Це вимагає мінімальних зусиль, щоб налаштувати. Додати діаграму так само просто:

.. diagram:: main

Якщо ви використовуєте кілька вихідних файлів Gaphor, вам потрібно визначити атрибут :model: і додати назви моделей до файлу конфігурації Sphinx (conf.py).

.. diagram:: main
   :model: example

На діаграми можна посилатися за їхнім іменем або за їхнім повним іменем.

.. diagram:: New model.main

Також можна застосувати Figure і Image properties:

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

   You can also add a caption, if you want.

Ви також можете додати підпис, якщо хочете.

Конфігурація

Щоб додати підтримку діаграм Gaphor до Sphinx, переконайтеся, що Gaphor зазначено як залежність.

Важливо

Gaphor вимагає принаймні Python 3.9.

По-друге, додайте наступне до свого файлу conf.py:

Крок 1: Додайте gaphor як розширення.

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

Крок 2: Додайте посилання на моделі

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

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

Тепер додайте директиви diagram у ваші документи.

Прочитайте документи

Директива diagram добре поєднується з Read the docs. Для відображення діаграм найкраще використовувати файл .readthedocs.yaml у вашому проекті. Переконайтеся, що ви включили додаткові apt_packages, як показано нижче.

Це файл .readthedocs.yaml, який ми використовуємо для 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

• Для створення PyGObject потрібен libgirepository-2.0-dev.

• gir1.2-pango-1.0 потрібен для відтворення тексту.

Примітка

Для Gaphor 2.7.0 gir1.2-gtk-3.0 і gir1.2-gtksource-4 є обов’язковими apt_packages, хоча ми не використовуємо GUI. Починаючи з Gaphor 2.7.1 і далі все, що вам потрібно, це GI-repository та Pango.

Помилки

Помилки відображаються на консолі під час створення документації та в документі.

У документації з’явиться помилка. Щось на зразок цього:

Помилка

Немає діаграми «Неправильна назва» в моделі «приклад» (../examples/sequence-diagram.gaphor).