Automatic layout
================

Every diagram so far placed shapes by hand with ``at``. For flow-style
diagrams you can hand placement to SheepText instead. Declare a ``layout
direction`` and connect the shapes — they arrange themselves along that axis:

.. sheeptext::
   :alt: Three boxes ingest process and store automatically arranged left to right with arrows between them

   layout direction right
   A: box "ingest"
   B: box "process"
   C: box "store"
   arrow from A to B
   arrow from B to C

``layout column`` (and its sibling ``layout row``) aligns a named set of shapes
into a single band. This column stacks three steps top to bottom:

.. sheeptext::
   :alt: Three boxes one two three stacked into an aligned vertical column

   layout column Pipe: A B C
   A: box "one"
   B: box "two"
   C: box "three"

``layout group`` arranges shapes *and* wraps them in a labelled container in one
declaration — no coordinates required:

.. sheeptext::
   :alt: Three boxes auth api and db grouped inside a labelled Services container

   layout group Svc "Services": A B C
   A: box "auth"
   B: box "api"
   C: box "db"

Automatic layout shines for flowcharts. Combine a downward flow with a ``layout
row`` for the two branch targets so they sit side by side; style the nodes by
role and let the arrows describe the branches:

.. sheeptext::
   :alt: A vertical flowchart from start to a validity check that branches yes to a process box and no to a reject box side by side

   layout direction down
   layout row Branches: Ok Bad
   Start: box "start" fill #dbeafe
   Check: box "valid?" fill #fef3c7
   Ok: box "process" fill #dcfce7
   Bad: box "reject" fill #fee2e2
   arrow from Start to Check
   from Check arrow "yes" to Ok
   from Check arrow "no" to Bad

A second edge between the same two shapes needs no help. SheepText gives each
edge its own attachment port, so a return arrow runs parallel to the outbound
one rather than on top of it:

.. sheeptext::
   :alt: Two boxes with a request arrow and a parallel return arrow, each on its own port

   layout direction right
   A: box "client"
   B: box "server"
   from A arrow "request" to B
   from B arrow "response" to A

Use ``route above`` or ``route below`` when you want an edge on a *particular*
side — to keep it away from other content, or simply to match how you would draw
it. It is a choice about which way an edge goes, not a fix for overlapping lines:

.. sheeptext::
   :alt: The same two boxes, with the return arrow forced onto a detour below them

   layout direction right
   A: box "client"
   B: box "server"
   from A arrow "request" to B
   from B arrow "response" to A route below

For pipeline diagrams, ``layout stage`` labels each phase and arranges its
members, much like ``layout group`` but tuned for left-to-right flow:

.. sheeptext::
   :alt: A two-stage pipeline with an Ingest stage feeding a Store stage

   layout direction right
   layout stage Ingest "Ingest": Collector
   layout stage Store "Store": Warehouse
   Collector: box "collector"
   Warehouse: box "warehouse"
   arrow from Collector to Warehouse

Next: bring in :doc:`icons`.