From: Matthew Watkins Date: Tue, 3 Mar 2026 15:16:43 +0000 (+0000) Subject: Docs: Add migration guide from blockdiag/seqdiag to Mermaid X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=4574530654bddf9a37134f66a4c82c7221554e11;p=doc.git Docs: Add migration guide from blockdiag/seqdiag to Mermaid sphinxcontrib-blockdiag and sphinxcontrib-seqdiag have not been maintained since December 2021 and are incompatible with Python 3.12+ (ast.NameConstant removal) and Pillow 10+ (ImageDraw.textsize removal). This adds a comprehensive documentation guide that: - Details the problems with the current blockdiag/seqdiag extensions - Evaluates alternatives (Mermaid, PlantUML, Graphviz) - Recommends sphinxcontrib-mermaid as the replacement - Provides step-by-step migration instructions for repositories - Includes syntax conversion examples for both block and sequence diagrams - Lists the changes needed in doc repo files (conf.py, requirements-docs.txt, upper-constraints.onap.txt) - Provides a downstream repository migration checklist Issue-ID: CIMAN-33 Change-Id: I3b6ce0eb31fca0f9ea36cbca75575b3ba6a33ea4 Signed-off-by: Matthew Watkins --- diff --git a/docs/guides/onap-documentation/diagrams-blockdiag-to-mermaid.rst b/docs/guides/onap-documentation/diagrams-blockdiag-to-mermaid.rst new file mode 100644 index 000000000..cc9bb39a1 --- /dev/null +++ b/docs/guides/onap-documentation/diagrams-blockdiag-to-mermaid.rst @@ -0,0 +1,660 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2026 The Linux Foundation + +.. _diagrams-blockdiag-to-mermaid: + +Migrating from blockdiag/seqdiag to Mermaid +============================================ + +This guide explains why the ONAP documentation project is replacing +``sphinxcontrib-blockdiag`` and ``sphinxcontrib-seqdiag`` with +``sphinxcontrib-mermaid``, and provides instructions for migrating +existing diagrams. + +.. contents:: Table of Contents + :depth: 3 + :local: + +Background +---------- + +The ONAP documentation toolchain has historically used two Sphinx extensions +from the `blockdiag `_ family for embedding +diagrams in reStructuredText: + +- **sphinxcontrib-blockdiag** --- block (box-and-arrow) diagrams +- **sphinxcontrib-seqdiag** --- sequence diagrams + +Both extensions are now effectively **abandoned** and cause cascading build +failures across ONAP repositories. This document details the problems, +evaluates alternatives, and provides a concrete migration path. + +Problem statement +----------------- + +Both packages were last released on **2021-12-05** (version 3.0.0) and have +received no maintenance since. Their classifiers list only Python 3.7--3.9 +as supported. The underlying ``blockdiag`` rendering library on which they +depend has the same maintenance status. + +The lack of maintenance creates two critical incompatibilities that currently +break ONAP documentation builds. + +Python 3.12+ incompatibility +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``sphinxcontrib-blockdiag`` (and its dependency ``blockdiag``) uses +``ast.NameConstant``, which was deprecated in Python 3.8 and **removed in +Python 3.12**. Any documentation build running on Python 3.12 or later will +crash with an ``AttributeError``. + +Repositories that set ``basepython = python3`` in ``tox.ini`` without pinning +a version are particularly affected, because modern CI runners resolve this to +Python 3.12 or newer. + +Pillow 10+ incompatibility +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``blockdiag 3.0.0`` calls ``ImageDraw.textsize()``, a method that was +deprecated in Pillow 9.2.0 and **removed in Pillow 10.0**. The ONAP +upper-constraints file pins ``Pillow===10.4.0``, so every repository that +renders a ``.. blockdiag::`` directive fails with: + +.. code-block:: text + + AttributeError: 'ImageDraw' object has no attribute 'textsize' + +The current workaround---forcing ``Pillow<10`` via ``commands_pre`` in +``tox.ini``---limits those repositories to Python 3.11 (Pillow 9.x does not +ship wheels for Python 3.12+), prevents them from receiving Pillow security +updates, and adds fragile per-repository configuration that is easy to forget. + +Impact on ONAP repositories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following table summarises how these incompatibilities have affected +ONAP documentation builds: + +.. list-table:: Affected Repositories and Workarounds + :header-rows: 1 + :widths: 30 40 30 + + * - Repository + - Issue + - Current Workaround + * - ``dmaap/buscontroller`` + - Pillow/blockdiag crash + - ``python3.11`` + ``Pillow<10`` + * - ``dmaap/datarouter`` + - Pillow/blockdiag crash + - ``python3.11`` + ``Pillow<10`` + * - ``sdc/sdc-docker-base`` + - ``ast.NameConstant`` crash on Python 3.12+ + - None (build broken) + * - ``ccsdk/distribution`` + - Extensions loaded but no directives in use + - Pinned constraints + +Evaluation of alternatives +-------------------------- + +Three actively maintained Sphinx extensions can produce the same types of +diagrams that ``blockdiag`` and ``seqdiag`` provide. + +sphinxcontrib-mermaid (recommended) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :widths: 25 75 + + * - **PyPI** + - `sphinxcontrib-mermaid `_ + * - **Repository** + - https://github.com/mgaitan/sphinxcontrib-mermaid + * - **Latest release** + - 2.0.0 (2026-01-13) + * - **Python support** + - 3.10--3.14 + * - **Diagram types** + - Flowcharts, sequence diagrams, Gantt charts, class diagrams, state + diagrams, ER diagrams, pie charts, git graphs, and more + * - **Runtime dependencies** + - ``sphinx``, ``jinja2``, ``pyyaml`` --- **no Pillow dependency** + * - **Rendering** + - Client-side JavaScript (Mermaid.js) for HTML output, or server-side + via the ``mmdc`` CLI for PDF/image output + * - **External tools** + - None required for HTML builds + +`Mermaid `_ is the industry-standard text-based +diagramming language, natively supported by GitHub, GitLab, Notion, Obsidian +and many other platforms. + +sphinxcontrib-plantuml (already in use) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :widths: 25 75 + + * - **PyPI** + - `sphinxcontrib-plantuml `_ + * - **Repository** + - https://github.com/sphinx-contrib/plantuml/ + * - **Latest release** + - 0.31 (2025-09-03) + * - **Python support** + - No explicit constraint (works with 3.8+) + * - **Diagram types** + - Sequence, class, activity, component, state, object, deployment, + timing, and many more + * - **External tools** + - **Requires Java** and the PlantUML JAR file + +ONAP already uses ``sphinxcontrib-plantuml`` in several repositories. +PlantUML is a capable alternative but requires a Java runtime, which +adds complexity to CI environments and local developer setups. + +sphinx.ext.graphviz (built-in) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :widths: 25 75 + + * - **Documentation** + - `sphinx.ext.graphviz `_ + * - **Maintenance** + - Maintained as part of Sphinx itself + * - **Diagram types** + - Directed and undirected graphs + * - **External tools** + - Requires the Graphviz ``dot`` binary + +Graphviz is well suited for dependency graphs and network topologies. It is +less natural for sequence diagrams and does not support the box-and-arrow +style that ``blockdiag`` provides. + +Comparison matrix +^^^^^^^^^^^^^^^^^ + +.. list-table:: Extension Comparison + :header-rows: 1 + :widths: 24 19 19 19 19 + + * - Criterion + - blockdiag/seqdiag + - Mermaid + - PlantUML + - Graphviz + * - Actively maintained + - **No** (last release 2021) + - **Yes** (2026-01) + - **Yes** (2025-09) + - **Yes** (part of Sphinx) + * - Python 3.12+ support + - **No** + - **Yes** (to 3.14) + - **Yes** + - **Yes** + * - Pillow dependency + - **Yes** (broken >=10) + - **No** + - No + - No + * - Block diagrams + - Yes + - **Yes** + - Yes + - Partial + * - Sequence diagrams + - Yes + - **Yes** + - Yes + - No + * - External runtime + - None + - **None** (HTML) + - Java + - Graphviz binary + * - GitHub rendering + - No + - **Yes** (native) + - No + - No + * - Single extension for both + - No (two packages) + - **Yes** + - Yes + - No + +Recommendation +-------------- + +**Replace both** ``sphinxcontrib-blockdiag`` **and** +``sphinxcontrib-seqdiag`` **with** ``sphinxcontrib-mermaid``. + +Key reasons: + +1. **One package replaces two** --- Mermaid handles both block and sequence + diagrams (and many more types) with a single Sphinx extension. + +2. **No Pillow dependency** --- eliminates the entire + ``ImageDraw.textsize()`` / ``Pillow<10`` compatibility problem. + +3. **No Java dependency** --- unlike PlantUML, Mermaid renders via + JavaScript for HTML output, with no external binary required for the + most common build target. + +4. **Python 3.10--3.14 support** --- future-proof, with no + ``ast.NameConstant`` issues. + +5. **Actively maintained** --- regular release cadence, latest release + January 2026. + +6. **Industry standard** --- Mermaid is natively rendered by GitHub, GitLab, + Notion, Obsidian, and many other platforms, so contributors can preview + diagrams without building the full documentation. + +7. **ReadTheDocs compatible** --- works with the Sphinx HTML builder without + any server-side tools. + +Migration guide +--------------- + +This section provides step-by-step instructions for migrating a repository +from ``blockdiag``/``seqdiag`` to Mermaid. + +Step 1 --- Update docs/conf.py +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Remove the old extensions and add the Mermaid extension: + +.. code-block:: python + + # Before + extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.graphviz', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', + 'sphinxcontrib.plantuml', + ] + + # After + extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.graphviz', + 'sphinxcontrib.mermaid', + 'sphinxcontrib.plantuml', + ] + +Step 2 --- Update requirements-docs.txt +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Replace the diagram extension entries: + +.. code-block:: text + + # Before + sphinxcontrib-blockdiag>=3.0.0 + sphinxcontrib-seqdiag>=3.0.0 + + # After + sphinxcontrib-mermaid>=1.0.0 + +If your repository also has an ``upper-constraints.onap.txt`` or similar +constraints file, update it accordingly: + +.. code-block:: text + + # Before + sphinxcontrib-blockdiag===3.0.0 + sphinxcontrib-seqdiag===3.0.0 + + # After + sphinxcontrib-mermaid===2.0.0 + +Step 3 --- Remove Pillow workarounds from tox.ini +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If your ``tox.ini`` contains workarounds for the Pillow/blockdiag +incompatibility, they can be removed: + +.. code-block:: ini + + # Remove this line if present: + commands_pre = pip install 'Pillow<10' + +You can also upgrade ``basepython`` from ``python3.11`` to ``python3.12`` +(or later) if it was held back specifically for blockdiag compatibility. + +Step 4 --- Convert blockdiag directives to Mermaid +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each ``.. blockdiag::`` directive must be rewritten as a ``.. mermaid::`` +directive. The examples below cover the most common patterns. + +Simple block diagram +"""""""""""""""""""" + +.. code-block:: rst + + .. blockdiag:: + + blockdiag { + A -> B -> C; + B -> D; + } + +Becomes: + +.. code-block:: rst + + .. mermaid:: + + graph LR + A --> B --> C + B --> D + +Block diagram with labels and colours +"""""""""""""""""""""""""""""""""""""" + +.. code-block:: rst + + .. blockdiag:: + + blockdiag { + A [label = "Client"]; + B [label = "Server", color = "#FF6600"]; + C [label = "Database"]; + A -> B -> C; + } + +Becomes: + +.. code-block:: rst + + .. mermaid:: + + graph LR + A["Client"] --> B["Server"] --> C["Database"] + style B fill:#FF6600,color:#fff + +Block diagram with groups +""""""""""""""""""""""""" + +.. code-block:: rst + + .. blockdiag:: + + blockdiag { + A -> B -> C; + + group { + label = "Group 1"; + color = "#99CCFF"; + A; B; + } + } + +Becomes: + +.. code-block:: rst + + .. mermaid:: + + graph LR + subgraph Group 1 + A --> B + end + B --> C + +Vertical orientation +"""""""""""""""""""" + +``blockdiag`` renders left-to-right by default. If you need top-to-bottom +flow (or if the original used ``orientation = portrait``): + +.. code-block:: rst + + .. mermaid:: + + graph TB + A --> B --> C + +The orientation keyword controls layout direction: + +- ``graph LR`` --- left to right (default blockdiag style) +- ``graph TB`` --- top to bottom +- ``graph RL`` --- right to left +- ``graph BT`` --- bottom to top + +Step 5 --- Convert seqdiag directives to Mermaid +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each ``.. seqdiag::`` directive must be rewritten as a ``.. mermaid::`` +directive using the ``sequenceDiagram`` type. + +Simple sequence diagram +""""""""""""""""""""""" + +.. code-block:: rst + + .. seqdiag:: + + seqdiag { + browser => webserver => database; + } + +Becomes: + +.. code-block:: rst + + .. mermaid:: + + sequenceDiagram + browser->>webserver: request + webserver->>database: query + database-->>webserver: result + webserver-->>browser: response + +.. note:: + + Mermaid sequence diagrams require explicit message labels on every arrow. + The ``seqdiag`` shorthand ``A => B => C;`` (which implies unlabelled + request-response pairs) must be expanded into individual messages with + descriptive labels. This improves documentation clarity. + +Sequence diagram with labels and notes +""""""""""""""""""""""""""""""""""""""" + +.. code-block:: rst + + .. seqdiag:: + + seqdiag { + browser -> webserver [label = "GET /index.html"]; + browser <-- webserver [label = "200 OK"]; + + browser -> webserver [label = "POST /api/data"]; + browser <-- webserver [label = "201 Created"]; + } + +Becomes: + +.. code-block:: rst + + .. mermaid:: + + sequenceDiagram + browser->>webserver: GET /index.html + webserver-->>browser: 200 OK + browser->>webserver: POST /api/data + webserver-->>browser: 201 Created + +Sequence diagram with activation and notes +"""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: rst + + .. seqdiag:: + + seqdiag { + browser -> webserver [label = "request"]; + webserver -> database [label = "query"]; + webserver <-- database [label = "result"]; + webserver -> webserver [label = "process"]; + browser <-- webserver [label = "response"]; + } + +Becomes: + +.. code-block:: rst + + .. mermaid:: + + sequenceDiagram + browser->>webserver: request + activate webserver + webserver->>database: query + database-->>webserver: result + webserver->>webserver: process + webserver-->>browser: response + deactivate webserver + +Mermaid arrow syntax reference +"""""""""""""""""""""""""""""" + +.. list-table:: Mermaid Sequence Diagram Arrow Types + :header-rows: 1 + :widths: 20 40 40 + + * - Arrow + - Meaning + - seqdiag equivalent + * - ``->>`` + - Solid line with arrowhead (synchronous) + - ``->`` or ``=>`` + * - ``-->>`` + - Dashed line with arrowhead (response) + - ``<--`` or ``<==`` + * - ``-)`` + - Solid line with open arrowhead (asynchronous) + - ``->`` (no direct equivalent) + * - ``--)`` + - Dashed line with open arrowhead + - (no direct equivalent) + * - ``-x`` + - Solid line with cross (lost message) + - (no direct equivalent) + +Step 6 --- Configure Mermaid options (optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can add optional Mermaid configuration to ``conf.py``: + +.. code-block:: python + + # Use a specific Mermaid JS version (default: latest) + mermaid_version = "11.4.1" + + # Generate raw Mermaid source alongside images for accessibility + mermaid_output_format = "raw" + + # For PDF output, specify the mmdc CLI path (requires Node.js) + # mermaid_cmd = "/usr/local/bin/mmdc" + +For HTML output (including ReadTheDocs), no additional configuration is +needed. The extension embeds Mermaid.js from a CDN by default. + +Step 7 --- Verify the build +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Run the documentation build locally and check that all diagrams render +correctly: + +.. code-block:: bash + + cd + tox -edocs + +Open the generated HTML in a browser and visually inspect each diagram. + +Changes to the doc repository +----------------------------- + +The central ``doc`` repository files will be updated as part of this +migration: + +docs/conf.py + Remove ``sphinxcontrib.blockdiag`` and ``sphinxcontrib.seqdiag`` from the + ``extensions`` list. Add ``sphinxcontrib.mermaid``. + +docs/requirements-docs.txt + Remove ``sphinxcontrib-blockdiag`` and ``sphinxcontrib-seqdiag``. Add + ``sphinxcontrib-mermaid>=1.0.0``. + +etc/upper-constraints.onap.txt + Remove ``sphinxcontrib-blockdiag===3.0.0`` and + ``sphinxcontrib-seqdiag===3.0.0``. Add ``sphinxcontrib-mermaid===2.0.0``. + The ``Pillow`` pin can remain at 10.4.0 as Mermaid does not depend on it. + +These changes will propagate to all downstream repositories that inherit +the shared documentation configuration. + +Downstream repository checklist +------------------------------- + +For each repository that currently uses ``blockdiag`` or ``seqdiag`` +directives, the following changes are required: + +.. list-table:: Migration Checklist + :header-rows: 1 + :widths: 5 60 35 + + * - # + - Action + - Files + * - 1 + - Replace ``sphinxcontrib.blockdiag`` and ``sphinxcontrib.seqdiag`` + with ``sphinxcontrib.mermaid`` in the extensions list + - ``docs/conf.py`` + * - 2 + - Replace ``sphinxcontrib-blockdiag`` and ``sphinxcontrib-seqdiag`` + with ``sphinxcontrib-mermaid`` in documentation requirements + - ``docs/requirements-docs.txt`` + * - 3 + - Update pinned versions if a local constraints file exists + - ``etc/upper-constraints.onap.txt`` + * - 4 + - Convert all ``.. blockdiag::`` directives to ``.. mermaid::`` + using the syntax examples in this guide + - ``docs/**/*.rst`` + * - 5 + - Convert all ``.. seqdiag::`` directives to ``.. mermaid::`` + using the syntax examples in this guide + - ``docs/**/*.rst`` + * - 6 + - Remove any ``commands_pre = pip install 'Pillow<10'`` workarounds + - ``tox.ini`` + * - 7 + - Upgrade ``basepython`` to ``python3.12`` if it was pinned to + ``python3.11`` solely for blockdiag compatibility + - ``tox.ini`` + * - 8 + - Build locally and verify all diagrams render correctly + - (local test) + +Further reading +--------------- + +- `Mermaid documentation `_ +- `Mermaid live editor `_ --- interactive browser-based + editor for prototyping diagrams +- `sphinxcontrib-mermaid documentation + `_ +- `sphinxcontrib-mermaid on PyPI + `_ +- `Mermaid syntax for flowcharts `_ +- `Mermaid syntax for sequence diagrams + `_ diff --git a/docs/guides/onap-documentation/index.rst b/docs/guides/onap-documentation/index.rst index ef2fc02c0..9d8b9eb35 100644 --- a/docs/guides/onap-documentation/index.rst +++ b/docs/guides/onap-documentation/index.rst @@ -18,6 +18,7 @@ contribute to the ONAP documentation project. creating-rst converting-to-rst updates-and-review + diagrams-blockdiag-to-mermaid api-swagger-guide api-swagger-json-pointer-fix templates/index