Diagrams that explain
=====================

Choose a diagram for a question. A flow chart explains a choice.
A block diagram explains responsibility. A sequence explains ordering.
A graph explains relationships. Use prose when it answers the question more directly.

A flow chart
------------

.. graphviz::
   :caption: Capacity is checked before storage is borrowed or grown.
   :alt: If capacity fits, run conversion; otherwise the host prepares storage and retries.

   digraph capacity {
     graph [rankdir=TB, bgcolor="transparent", pad="0.3"];
     node [shape=box, style="rounded,filled", fillcolor="#edf5f2",
           color="#216553", fontname="Helvetica", fontcolor="#16382f"];
     edge [color="#216553", fontname="Helvetica", fontsize=10];
     need [label="Measure the required capacity"];
     fits [label="Fits caller storage?", shape=diamond];
     run [label="Convert without allocation"];
     grow [label="Host checks budget\nand prepares storage"];
     need -> fits;
     fits -> run [label="yes"];
     fits -> grow [label="no"];
     grow -> need [label="retry"];
   }

The drawing names the owner at the growth step.
It does not suggest that the conversion core allocates.
This distinction is part of the contract.

Author a graph
--------------

.. code-block:: rst

   .. graphviz::
      :caption: Parsing precedes resolution.
      :alt: The source becomes a tree, then references are resolved.

      digraph pipeline {
        graph [rankdir=LR, bgcolor="transparent"];
        node [shape=box];
        "source" -> "tree" -> "resolved tree";
      }

``graphviz``, ``graph``, and ``digraph`` are built in.
Guidedog renders them through Graphviz. HTML receives an SVG asset.
PDF embeds the rendered drawing. Both use the same graph source.

Make the result legible
-----------------------

Keep node labels short. Explain a longer rule below the drawing.
Prefer one direction for the main path. Label a return edge with its condition.
Use shape and text as well as color. A print reader may have no color at all.

Supply alternative text and a caption. Test narrow browser windows and the PDF page.
If a diagram needs tiny type to fit, split it into two drawings.
See :doc:`../media` for image and figure sizing.