Generating Documentation

Transit can generate both state diagrams and transition tables directly from your type-level specification. Both generation processes use the same approach: reflectType converts your type-level DSL specification to a term-level equivalent, which can then be used to generate the documentation.

doorTransit :: TransitCore
doorTransit = reflectType (Proxy @DoorTransit)

^{🗎 test/Examples/Door.purs L47-L48}

State Diagrams

Transit can generate state diagrams using Graphviz¹. For this we’ll use the following function from the Transit.Render.Graphviz module:

generate :: TransitCore -> (Options -> Options) -> GraphvizGraph

It takes the TransitCore value which we’ve created in the previous step and a function that takes the default options and returns the options we want to use. Now we have everything in place to generate the state diagram:

generateGraphDark :: Effect Unit
generateGraphDark =
  let
    graph :: GraphvizGraph
    graph = TransitGraphviz.generate doorTransit \def -> def
      { theme = themeHarmonyDark
      , layout = Portrait
      }
  in
    FS.writeTextFile UTF8 "renders/door_graph-dark.dot" (Graphviz.toDotStr graph)

^{🗎 test/Examples/Door.purs L104-L113}

Generated Output: This code produces the diagram we examined at the beginning of this example.
🔗 View diagram on GraphvizOnline

The options we’re using above are:

• The theme option we’re using above controls the color scheme. Transit provides a couple of built-in themes, but you can also provide your own. See themes.md for more details.

• The layout option controls the layout of the graph. We’re using Portrait here, which is the default layout. But you can also use Landscape, Circular, or Manual to position the nodes manually, as we’ll see later.

Finally, to convert the .dot file to an SVG (or other formats), use the Graphviz command-line tools:

dot -Tsvg renders/door_graph.dot -o renders/door.svg

Transition Tables

In addition to state diagrams, you can also generate transition tables from the same specification. This provides a tabular view of all state transitions, which can be easier to read for some use cases.

generateTable :: Effect Unit
generateTable = do
  let
    table :: Table
    table = TransitTable.generate doorTransit \def -> def

  FS.writeTextFile UTF8 "renders/door_table.md" (Table.toMarkdown table)

^{🗎 test/Examples/Door.purs L115-L121}

Here we provide no options to the generate function, so we use the identity function \def -> def to pass the default options.

Generated Output: This generates the transition table shown earlier, with rows for each valid state transition.