Axional Docs
can be done through graphviz, ditaa & sequence diagrams.
Three graph implementation methods are available at Axional Docs
:
- graphviz tag: <graph title"...">
- ditaa tag: <ditaa>
- Sequence diagrams tag: <graph-sequence>
1 Graphviz
Graphviz is an open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. It has an important applications in networking, bioinformatics, software engineering, database and web design, machine learning and in visual interfaces for other technical domains.
To utilize graphviz in Axional Docs
the tag <graph> </graph> is used.
The graphs might be scaled to make them bigger or smaller using the attribute scale.
The graphviz layout programs take descriptions of graphs in a simple text language and makes "hierarchical" or layered drawings of directed graphs.
Graphs are written following this structure. Graph or digraph will be selected depending on the situation.
<graph title='Title of Graph' scale=".6"(optional)> graph nameOfGraph(optional) { Code of Graph } </graph>
You can find more info by clicking in this link: More info.
1.1 Syntax
1.1.1 Graph or Digraph
Graphviz allows us to create two different kind of graph
- Simple Graph: This is an non directed graph ( graph)
- Digraph: This is a directed graph ( digraph)
A graph must be specified as either a digraph or a graph. Semantically, this indicates whether or not there is a natural direction from one of the edge's nodes to the other. Lexically, a digraph must specify an edge using the edge operator -> while a non directed graph must use --. Operationally, the distinction is used to define different default rendering attributes. For example, edges in a digraph will be drawn, by default, with an arrowhead pointing to the head node. For ordinary graphs, edges are drawn without any arrowheads by default.
Simple Graph
To write an non directed graph the option " graph" will be selected and the connections will be written with " --"
Code
<section title='Graph example'> <graph title='Non directed graph'> graph { NodeA -- NodeB; } </graph> </section>
Graph
Non directed graph
Digraph
To write a directed graph the option " digraph" will be selected and the connections will be written with " ->"
Code
<section title='Graph example'> <graph title='Directed graph'> digraph { NodeA -> NodeB; } </graph> </section>
Graph
Directed graph
This is an example of a simple digraph
Code
<section title='Graph example'> <graph title='Directed graph'> digraph { a -> b[label="0.2",weight="0.2"]; c -> b[label="0.6",weight="0.6"]; c -> e[label="0.6",weight="0.6"]; e -> e[label="0.1",weight="0.1"]; e -> b[label="0.7",weight="0.7"]; } </graph> </section>
Graph
Digraph Example
1.1.2 Add Nodes
This is a first example of how graphviz nodes are implemented and how nodes are connected between them.
Code
<section title='Example 1 Graphviz'> <graph title='Example 1 Graphviz'> digraph G { main -> parse -> execute; main -> init; main -> cleanup; execute -> make_string; execute -> printf init -> make_string; main -> printf; execute -> compare; } </graph> </section>
Graph
Add nodes example
1.1.3 Drawing Attributes
The next example shows how to change different drawing attributes
Code
<section title='Example 2 Graphviz'> <graph title='Drawing Attributes'> digraph G { size ="4,4"; main [shape=box]; /* this is a comment */ main -> parse [weight=8]; parse -> execute; main -> init [style=dotted]; main -> cleanup; execute -> { make_string; printf} init -> make_string; edge [color=red]; main -> printf [style=bold,label="100 times"]; make_string [label="make a\nstring"]; node [shape=box,style=filled,color=".7 .3 1.0"]; execute -> compare; cleanup [shape=polygon,sides=5,peripheries=3,color=lightblue,style=filled]; //Other shapes are allowed } </graph> </section>
Graph
Drawing attributes
After the code line "edge [color=red];": All the other lines rendered are painted in red.
The same happens after "node [shape=box,style=filled,color=".7 .3 1.0"];", all the following found nodes are rendered with this characteristics
1.1.4 Subgraphs and Clusters
Subgraphs play three roles in Graphviz. First, a subgraph can be used to represent graph structure, indicating that certain nodes and edges should be grouped together. This is the usual role for subgraphs and typically specifies semantic information about the graph components. It can also provide a convenient shorthand for edges. An edge statement allows a subgraph on both the left and right sides of the edge operator. When this occurs, an edge is created from every node on the left to every node on the right. For example, the specification
A -> {B C}
Is equivalent to:
A -> B A -> C
In the second role, a subgraph can provide a context for setting attributes. For example, a subgraph could specify that blue is the default color for all nodes defined in it. In the context of graph drawing, a more interesting example is:
subgraph { rank = same; A; B; C; }
This (anonymous) subgraph specifies that the nodes A, B and C should all be placed on the same rank if drawn using dot.
The third role for subgraphs directly involves how the graph will be laid out by certain layout engines. If the name of the subgraph begins with cluster, Graphviz notes the subgraph as a special cluster subgraph. If supported, the layout engine will do the layout so that the nodes belonging to the cluster are drawn together, with the entire drawing of the cluster contained within a bounding rectangle. Note that, for good and bad, cluster subgraphs are not part of the DOT language, but solely a syntactic convention adhered to by certain of the layout engines.
Subgraph
The next example shows how make a subgraph
Code
<section title='Example 3 Graphviz'> <graph title='Example 3 Graphviz'> digraph G { compound=true; subgraph cluster0 { a -> b; a -> c; b -> d; c -> d; } subgraph cluster1 { e -> g; e -> f; } b -> f [lhead=cluster1]; d -> e; c -> g [ltail=cluster0, lhead=cluster1]; c -> e [ltail=cluster0]; d -> h; } </graph> </section>
Graph
Subgraphs example
Only new nodes are situated inside the subgraph
1.2 Graphviz examples
The following section show example of graphviz.
Code
<section title='Example 4 Graphviz'> <graph title="Application view"> digraph { graph [fontsize=10 fontname="Verdana" compound=true]; node [shape=record fontsize=10 fontname="Verdana" style=filled fillcolor="#99ccff"]; edge [color=gray]; overlap=scale; # (try to) stretch everything if edges overlap splines=ortho; subgraph cluster_1 { style=dotted; label="J2EE Server Node #1"; HTTP -> Filters; Filters -> REST; Filters -> SOAP; Filters -> Servlet; REST -> Application; SOAP -> Application; Servlet -> Application; Application -> JDBC; JDBC -> EJBCache; } subgraph cluster_db { label="Databases"; db1 db2 } internet -> balancer; balancer -> HTTP; JDBC -> db1; EJBCache -> db1; JDBC -> db2; EJBCache -> db2; Application [style=filled fillcolor="#00cc00"]; EJBCache [style=filled fillcolor="#00cc00"]; internet [style=filled fillcolor="#ff3300" fontcolor="#FFFFFF"]; balancer [style=filled fillcolor="#ff0066" fontcolor="#FFFFFF"]; db1 [style=filled fillcolor="#cccc00" fontcolor="#FFFFFF" label="Primary DB"]; db2 [style=filled fillcolor="#cccc00" fontcolor="#FFFFFF" label="Replica DB"]; } </graph> </section>
Graph
Example
Code
<section title='Example 5 Graphviz'> <graph scale=".8" title="4 tier (Axional Ecom)"> digraph G { node [shape=record fontsize=10 fontname="Verdana"]; rankdir=LR; Recursos -> "Front End Server" -> "Back End Server" -> Database } </graph> </section>
Graph
Example
Code
<section title='Example 6 Graphviz'> <graph scale=".6" title="BlockingQueuePool lifecycle"> digraph { request -> decision used [style="fill:#FFBF00"]; free [style="fill:#01A9DB"]; failed [style="fill:#FF0000"]; use [shape=circle, style="fill:#40FF00"] space [shape=diamond, label="size < PoolMaxSize ?"]; time_a [shape=diamond, label="t < AcquireTimeout ?"]; time_c [shape=diamond, label="t < BornDieTimeout ?"]; subgraph Health { health1 [shape=diamond, label="Expired ?"]; health2 [shape=diamond, label="used > CheckOutCount ?"]; health3 [shape=diamond, label="Health ok ?"]; } ofactory [shape=ellipse, label="Object Factory"]; decision [shape=diamond, label="Exists in free pool ?"]; decision -> free [label="Yes"]; decision -> space [label="No"]; free -> health1 health1 -> health2 [label="No"]; health1 -> ofactory [label="Yes"]; health2 -> health3 [label="No"]; health2 -> ofactory [label="Yes"]; health3 -> ofactory [label="No"]; health3 -> used [label="Yes"]; space -> ofactory [label="Yes"]; ofactory -> create create -> time_c time_c -> used [label="Yes"]; time_c -> failed [label="No"]; space -> time_a [label="No"]; time_a -> failed [label="No"]; time_a -> decision [label="Yes"]; used -> use use -> free } </graph> </section>
Graph
Example
To test new graphs using graphviz click here or
2 Ditaa
Ditaa is a small command-line utility written in Java, that can convert diagrams drawn using ascii art ('drawings' that contain characters that resemble lines like | / - ), into proper bitmap graphics. Ditaa interprets ascii art as a series of open and closed shapes, but it also uses special markup syntax to increase the possibilities of shapes and symbols that can be rendered. This is best illustrated by the following example
More info on http://ditaa.sourceforge.net/.
To use ditaa in Axional Docs
the tag <ditaa> </ditaa> is used.
yum install fontconfig
Code
<section title='ditaa1'> <ditaa> <![CDATA[ +--------+ +-------+ +-------+ | | --+ ditaa +--> | | | Text | +-------+ |diagram| |Document| |!magic!| | | | {d}| | c478 | | | +---+----+ +-------+ +-------+ : ^ | Lots of work : +-------------------------+ ]]> </ditaa> </section>
Result
2.1 Syntax
2.1.1 Tags
Some tags may be used to set different formats to the different boxes. The tags must be written inside the ASCII box at which they are referring.
Tag | Description |
---|---|
{c} | decision(Choice) |
{d} | document |
{io} | input/output, parallelogram |
{mo} | manual operation |
{o} | ellipse, circle |
{s} | storage |
{tr} | trapezoid (looks like an inverted {mo} ) |
Ditaa recognises some tags that change the way a rectangular shape is rendered. All tags are between { and }. See the table below:
These dhapes can be combined in several layout structures. For instance:
2.1.2 Corners
Corners can be painted as a sharp corner or as a round corner. If you use / and \ to connect corners, they are rendered as round corners. Meanwhile if you use + to connect corners, they are rendered as sharp corners
Code
<section title='ditaa1'> <ditaa> <![CDATA[ /--+ | | +--/ ]]> </ditaa> </section>
Result
2.1.3 Colour
Color codes can be used to add color to the diagrams. The syntax of color codes is "cXXX" where "XXX" is a hex number. The first digit of the number represents the red component of the color, the second digit represents green and the third blue (good ol' RGB). See below for an example of use of color codes:
Code
<section title='ditaa1'> <ditaa> <![CDATA[ /----\ /----\ |c33F| |cC02| | | | | \----/ \----/ /----\ /----\ |c1FF| |c1AB| | | | | \----/ \----/ ]]> </ditaa> </section>
Result
Some colours can be called with a human readable color codes:
Code
<section title='ditaa1'> <ditaa> <![CDATA[ /-------------+-------------\ |cRED RED |cBLU BLU | +-------------+-------------+ |cGRE GRE |cPNK PNK | +-------------+-------------+ |cBLK BLK |cYEL YEL | \-------------+-------------/ ]]> </ditaa> </section>
Result
As you can see above, if a colored shape contains any text, the color of the text is adjusted according to the underlying color. If the underlying color is dark, the text color is changed to white (from the default black).
Note that color codes only apply if they are within closed shapes, and they have no effect anywhere outside.
Set of ccolors
List of common HTML color codes
Color chart
2.1.4 Lines
Lines, connection lines or box lines, can be rendered continuous or dashed. Any element that contain either at least one = (for horizontal lines) or at least one : (for vertical lines) are rendered as dashed lines, otherwise a continuous line will be rendered.
Code
<section title='ditaa1'> <ditaa> <![CDATA[ ----+ /----\ +----+ ----+ /----\ +----+ : | | : | | | | | | | | | |{s} | | | | |{s} | v \-=--+ +----+ v \----+ +----+ ]]> </ditaa> </section>
Result
2.1.5 Point markers
If * is encountered on a line (but not at the end of the line), it is rendered as a special marker, called the point marker
Code
<section title='ditaa1'> <ditaa> <![CDATA[ *----* | | /--* * * | | | -*--+ *----* ]]> </ditaa> </section>
Result
2.2 ditaa examples
Now you can find some more complex ditaa examples:
Code
<section title='ditaa1'> <ditaa> <![CDATA[ | | programmers | maintainers maintainers | users | | +----+----+ +---+----+ /--------------\ | | | | |regular commit+----=---+ default | | stable | \--------------/ | | | | | | | | /--------------\ | | | | |regular commit+----=---+ | | | \--------------/ | | | | | +-------release merge--->| | ... | | | | | | | | | | /-----------\ | | | |<-merge-+release tag+-=-+ | | | \-----------/ | cBLU | | | | | +----------------+ | | | | | |<--+ | | | | feature branch | | cGRE | | | | {d} | | {d} | | {d} | +----+------+----+ | | /-----------\ | | : | | |<-merge-+hotfix cRED+-=-+ | | | | | \-----------/ | | | | | | | | | +-merge->| | | | | | | | | | +---------+ +--------+ | /-------+------\ |regular commit| +--------------------+ \--------------/ | Glossary | | | ... | --- branch change | | -=- stay on branch | +--------------------+ ]]> </ditaa> </section>
Result
Code
<section title='ditaa1'> <ditaa> <![CDATA[ | | programmers | maintainers maintainers | users | | +----+----+ +---+----+ /--------------\ | | | | |regular commit+----=----+ default | | stable | \--------------/ | | | | | | | | /--------------\ | | | | |regular commit+----=----+ | | | \--------------/ | | | | | +------------release merge------>| | ... | | | | | | | | | | /-----------\ | | | |<-merge------+release tag+-=----| | | | \-----------/ | | | | | | | | | | | | /----------------------\ | | | | |maintained release 1.x+-=--| | | | \-----------+----------/ | cBLU | +----------------+ | | | | | | |<---+ | : | | | feature branch | | cGRE | v | | | {d} | | {d} | /-----------\ | {d} | +----+------+----+ | | |hotfix cRED| | | : | | | \-------+---/ | | | | | | | | | | | | | : | | | | | | v | | | | | | /-------------------\ | | | | | | |release tag 1.(x+1)| | | | | | | \----------+--------/ | | | | | | | | | | | | | merge | | | | | | : | | | | | | v | | | | | | /----------------------\ | | | | | | |maintained release 2.y| | | | | | | \-----------+----------/ | cBLU | | | | | | | | | | | | : | | | | | | v | | | | | | /-------------------\ | | | | | | |release tag 2.(y+1)+-=-merge->| | | | | | \-------------------/ | | | | | | ... | | | | | | | | | +-merge-->| |<--------merge hotfix-----------+ | | | | | | | +---------+ +--------+ | /-------+------\ |regular commit| +--------------------+ \--------------/ | Glossary | | | ... | --- branch change | | -=- stay on branch | +--------------------+ ]]> </ditaa> </section>
Result
Code
<section title='ditaa1'> <ditaa> <![CDATA[ | | programmers | maintainers maintainers | users | | +----+----+ +---+----+ /--------------\ | | | | |regular commit+----=---+ default | +----------------+ | stable | \--------------/ | | | | | | | +-->+ nextrelease | | | /--------------\ | | | c1AB {d} | | | |regular commit+----=---+ | +---+------+-----+ | | \--------------/ | | | | | | ... | | : | | | | | | | | | | | /---+---\ | | | | +-->+ graft | | | | | | \-------/ | | | | | ... | | | | | v | | | | | | | | release merge-->| | | | | | | | | | | | /-----------\ | | | |<-merge-+release tag+-=-+ | | | \-----------/ | cBLU | | | | | +----------------+ | | | | | |<--+ | | | | feature branch | | cGRE | | | | {d} | | {d} | | {d} | +----+------+----+ | | /-----------\ | | : | | |<-merge-+hotfix cRED+-=-+ | | | | | \-----------/ | | | | | | | | | +-merge->| | | | | | | | | | +---------+ +--------+ | /-------+------\ |regular commit| +--------------------+ \--------------/ | Glossary | | | ... | --- branch change | | -=- stay on branch | +--------------------+ ]]> </ditaa> </section>
Result
3 Sequence diagrams
Axional Docs
provides a way to print sequence diagrams. The tag graph-sequence
is used for this purpose.
Each sequence diagram must start with this element.
The following table shows what elements could be included in sequence diagrams.
This element allows users to print sequence diagrams.
<graph-sequence title='title'>
<participant name='name' /> *
<message
from='from'
to='to'
type='solid|dotted|solid_arrow|dotted_arrow|solid_async|dotted_async'
active='yes|no'
/> *
<alt> *
<if expr='expr'> +
<alt /> *
<loop /> *
<message /> *
<note /> *
<opt /> *
</if>
</alt>
<opt expr='expr'> *
<alt /> *
<loop /> *
<message /> *
<note /> *
<opt /> *
</opt>
<loop statement='statement'> *
<alt /> *
<loop /> *
<message /> *
<note /> *
<opt /> *
</loop>
<note
position='right|left|over'
of='of'
/> *
</graph-sequence>
Nodes | |||||
---|---|---|---|---|---|
Name | Type | Required | Unique | Default | Description |
graph-sequence | |||||
Atitle | string | Sequence diagram's title. | |||
Eparticipant | Creates objects or classes in UML language. These are sequence diagram participants. It is optional to define participants. If not defined, when messages are created, participants are created at the same time. If you want to define a specific order between participants then it is mandatory to use this element. | ||||
Aname | string | Participant's name. | |||
Emessage | Allows user to create a message between participants. | ||||
Afrom | string | Message emitter. | |||
Ato | string | Message receiver. | |||
Atype | string | solid_arrow | Message type. The message line style depends on the type of message. | ||
Aactive | string | no | Activates message receiver state. | ||
Ealt | This element defines an alternative block in the sequence diagram. | ||||
Eif | |||||
Aexpr | string | Defines the if expression that defines sequence diagram workflow. | |||
Ealt | |||||
Eloop | |||||
Emessage | |||||
Enote | |||||
Eopt | |||||
Eopt | This element defines an optional alternative. | ||||
Aexpr | string | Optional expression. | |||
Ealt | |||||
Eloop | |||||
Emessage | |||||
Enote | |||||
Eopt | |||||
Eloop | Allow to create a loop block. | ||||
Astatement | The loop statement that makes it iterate. | ||||
Ealt | |||||
Eloop | |||||
Emessage | |||||
Enote | |||||
Eopt | |||||
Enote | This element create notes in the sequence diagram. | ||||
Aposition | string | Specifies position of the note relative to the participants defined in of attribute. | |||
Aof | string | Contains one or more participants. The note position is relative to those. If more than one participants are defined because of over option used in position, the names must be separated by comma. Example: of='Alice,John' |
Some examples of Axional Docs
sequence diagrams
<graph-sequence title="Alice - John conversation"> <message from="Alice" to="John">Hello John, how are you?</message> <message from="John" to="Alice" type='dotted_arrow'>Great!</message> </graph-sequence>
Alice - John conversation
<graph-sequence title="Sequence diagram activation"> <message from="Alice" to="John" active='yes'>Hello John, how are you?</message> <message from="John" to="Alice" type='dotted_arrow' active='no'>Great!</message> </graph-sequence> <graph-sequence title="Sequence diagram more than one activation"> <message from="Alice" to="John" active='yes'>Hello John, how are you?</message> <message from="Alice" to="John" active='yes'>John, can you hear me?</message> <message from="John" to="Alice" type='dotted_arrow' active='no'>Hi Alice, I can hear you!</message> <message from="John" to="Alice" type='dotted_arrow' active='no'>I feel great!</message> </graph-sequence>
Sequence diagram activation
Sequence diagram more than one activation
<graph-sequence title="Sequence diagram note"> <message from="Alice" to="John">Hello John, how are you?</message> <note position="over" of="Alice,John">A typical interaction</note> </graph-sequence>
Sequence diagram note
<graph-sequence title="Sequence diagram loop"> <message from="Alice" to="John">Hello John, how are you?</message> <loop statement='A typical interaction'> <message from="John" to="Alice">Great!</message> </loop> </graph-sequence>
Sequence diagram loop
<graph-sequence title="Sequence diagram alt"> <message from="Alice" to="Bob">Hello Bob, how are you?</message> <alt> <if expr='is sick'> <message from='Bob' to='Alice'>Not so good :(</message> </if> <if expr='Feeling fresh like a daisy'> <message from='Bob' to='Alice'>Feeling fresh like a daisy</message> </if> </alt> <opt expr="is sick"> <message from="Bob" to="Alice">Not so good :(</message> </opt> </graph-sequence>
Sequence diagram alt
<graph-sequence title="Sequence diagram three participants example"> <participant name='Alice' /> <participant name='Bob' /> <message from="Alice" to="John">Hello John, how are you?</message> <loop statement='Healthcheck'> <message from="John" to="John">Fight against hypochondria</message> </loop> <note position="right" of="John">Rational thoughts prevail...</note> <message from="John" to="Alice">Great!</message> <message from="John" to="Bob">How about you?</message> <message from="Bob" to="John">Jolly good!</message> </graph-sequence>
Sequence diagram three participants example
4 Graph Gallery
Writing nice explanations can be reinforced with designs, graphs or conceptual flowcharts. Here in after there is a wide range of examples that ara available all around this site.