Physical network diagram generated from dot config language

Is there a good and easy solution to automatically generate logical or physical network diagrams? Trying answer this question I've been playing today with the dot configuration language to test it in the field.

Automatically generated diagram

The DOT config file 

graph physical_net_topology {
 
legend [ label="{ legend | {red | public} |{blue| v1002 inside} | {green | v105 dmz} }", shape=record];


subgraph cluster_sp {
    label="pub switch";

    graph [ fillcolor="burlywood", style="filled"]
    node [shape=record,fillcolor="white", style="filled"]
    edge[style=invis];
    
    node [label="3"] p3 ;
    node [label="2"] p2 ;
    node [label="1"] p1 ;

    { rank=same; p1; p2; p3}
    p1 -- p2 -- p3;
}

subgraph cluster_si {
    label="Internal switch";

    edge[style=invis];
    node [shape=record ];

    node [label="1"] e1 ;
    node [label="2"] e2 ;
    node [label="3"] e3 ;
    node [label="4"] e4 ;
    node [label="5"] e5 ;
    node [label="6"] e6 ;

    { rank=same; e1; e2; e3; e4; e5; e6;}
    e1 -- e2 -- e3 -- e4 -- e5 -- e6;
}

subgraph cluster_fw1 {
    label="FW1 ports";

    graph = [ style = rounded]
    edge[style=invis]
    
    node [shape=record ];
    node [label="1"] f1 ;
    node [label="2"] f2 ;
    node [label="3"] f3 ;
    node [label="4"] f4 ;

  { rank=same; f1; f2; f3; f4; }

  f1 -- f2 -- f3 -- f4'
}

p2 -- f1 [color="red"]
f2 -- e1 [color="blue"]
f3 -- e2 [color="green"]

e3 -- server1 [color="green"]
e4 -- server2 [color="green"]
e6 -- server3 [color="blue"]

}

Results discussion

It took me a good couple of hours to write this config. Even after that I still have only a very basic understanding of how flexible the dot language is. The coding was very laborious. It required a lot of trying and testing if the new generated graph is what you are looking for.

Often the options I was trying didn't have any effect.

The documentation I found and read wasn't explaining all the details so trying and intuition was often your only friend.

References

http://sandbox.kidstrythisathome.com/erdos/
http://graphviz-dev.appspot.com/
http://www.graphviz.org/

http://rtomaszewski.blogspot.co.uk/search/label/diagram

ASCII diagram tells more than a full page of text

Before anyone can help you they need to understand you first. Below is an example why a single picture is worth more than than full page of text.

Problem

How long would it take to explain to somebody that:

• VLAN1 is used ONLY for inter VM communication
• VMs in VLAN2 and 3 are in isolated network segments that have internet access
• VMs in VLAN2 and 3 can talk to each other (using the FW as its default gateway to route traffic)

Solution

ASCII diagram:
                                               +---+------------+
                                               |   |            |
          ^                                    | v |------------|
          | internet                           | m |  vm2       |
          |                         vlan1      | 1 |------------|
      +---+---+         +-------+   vlan2      |   |  vm3       |
      | FW    | <-------|switch1| ------------ |----------------|
      +-------+   vlan3 +-------+   vlan3      |virt1 |virt2 |  |
                  vlan2     ^                  |switch|switch|  |
                            |                  |------+------+--|
                            |                  | Hypervisor1    |
                            | trunk            +----------------+
                            | vlan1
                            |
                            |
                            +
                       +-----------+  vlan1            
                       |aggregation|  vlan2    +-------------+
                       |-----------+<--------- | vm1 vm2     |
                       | switch    |  trunk    |-------------|
                       +-----------+           | Hypervisor2 |
                                               +-------------+

References

http://www.asciiflow.com/#Draw
http://www.streamwave.com/web-development/ascii-diagram-tools/
http://nedbatchelder.com/blog/200911/ditaa_diagrams_through_ascii_art.html

How to document python code

There are couple of way how you can document a python code. In this article I'm not trying to compare them but rather to show how a final documentation may look like.

Problem

How many tools can we use to generate documentation from python source.
How a final documentation look like after generation from a source code.

Analysis

When searching on Google we quickly find that the most popular are (there are more that I'm not listing here):

• epydoc
• sphinx 
• doxygen

Example

These are examples how the documentation looks like.

Epydoc - It has as stile of a classical javadoc documentation introduced by Sun when Java was released.

Sphinx - the layout is very different from Epydoc. It seems to be very likable by the python project itself. All the doc for it is generated using it.

Demonstration

Epydoc installation

# python --version
Python 2.7.3
# aptitude show python-epydoc
# aptitude install  python-epydoc
# aptitude install apache2

The source code

Generation of epydoc documentation

# epydoc --verbose --verbose  example_epydoc.py
Building documentation
[  0%] example_epydoc (example_epydoc.py)
Merging parsed & introspected information
[  0%] example_epydoc
Linking imported variables
[  0%] example_epydoc
[ 12%] example_epydoc.MyClass
Indexing documentation
[  0%] example_epydoc
Checking for overridden methods
[ 12%] example_epydoc.MyClass
Parsing docstrings
[  0%] example_epydoc
[ 12%] example_epydoc.MyClass
Inheriting documentation
[ 12%] example_epydoc.MyClass
Sorting & Grouping
[  0%] example_epydoc
[ 12%] example_epydoc.MyClass
Writing HTML docs to 'html'
[  4%] epydoc.css
[  9%] epydoc.js
[ 13%] identifier-index.html
[ 45%] module-tree.html
[ 50%] class-tree.html
[ 54%] help.html
[ 59%] frames.html
[ 63%] toc.html
[ 68%] toc-everything.html
[ 72%] toc-example_epydoc-module.html
[ 77%] example_epydoc-module.html
[ 81%] example_epydoc.MyClass-class.html
[ 86%] example_epydoc-pysrc.html
[ 90%] redirect.html
[ 95%] api-objects.txt
[100%] index.html

Timing summary:
  Building documentation.............     0.2s |=================================================
  Merging parsed & introspected i....     0.0s |
  Linking imported variables.........     0.0s |
  Indexing documentation.............     0.0s |
  Checking for overridden methods....     0.0s |
  Parsing docstrings.................     0.0s |=
  Inheriting documentation...........     0.0s |
  Sorting & Grouping.................     0.0s |
  Writing HTML docs to 'html'........     0.0s |=======

Showing the doc

You have to configure the Apache and points it to the generated 'html' directory. Once the page is loaded in the browser the documentation looks like this:

References

1. http://stackoverflow.com/questions/4126421/how-to-document-python-code-epydoc-doxygen-sphinx
2. http://stackoverflow.com/questions/1125970/python-documentation-generator
3. http://stackoverflow.com/questions/5334531/python-documentation-standard-for-docstring
4. http://epydoc.sourceforge.net/
5. http://sphinx-doc.org/