Added Sphinx diagram tools

Added some tools and example
- blockdiag for block diagram
- nwdiag for network diagram
- actdiag for act diagram
- seqdiag for sequence diagram

Change-Id: Idc709dca40f756a66beca5ab5da2a377b04338d2

doc/source/conf.py

@@ -30,6 +30,10 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode',
+              'sphinxcontrib.blockdiag',
+              'sphinxcontrib.actdiag',
+              'sphinxcontrib.seqdiag',
+              'sphinxcontrib.nwdiag',
               'oslosphinx'
              ]
 

requirements.txt

@@ -1,6 +1,14 @@
+actdiag
+blockdiag
 docutils==0.9.1
+nwdiag
 oslosphinx
 pbr>=0.6,<1.0
+seqdiag
 sphinx>=1.1.2,<1.2
+sphinxcontrib-actdiag
+sphinxcontrib-blockdiag
+sphinxcontrib-nwdiag
+sphinxcontrib-seqdiag
 testrepository>=0.0.18
 testtools>=0.9.34

specs/template.rst

@@ -33,12 +33,80 @@ Some notes about using this template:
 * To test out your formatting, build the docs using tox, or see:
   http://rst.ninjs.org
 
-* If you would like to provide a diagram with your spec, ascii diagrams are
+* If you would like to provide a diagram with your spec, text representations
-  required.  http://asciiflow.com/ is a very nice tool to assist with making
+  are preferred. http://asciiflow.com/ is a very nice tool to assist with
-  ascii diagrams.  The reason for this is that the tool used to review specs is
+  making ascii diagrams. blockdiag is another tool. These are described below.
-  based purely on plain text.  Plain text will allow review to proceed without
+  If you require an image (screenshot) for your BP, attaching that to the BP
-  having to look at additional files which can not be viewed in gerrit.  It will
+  and checking it in is also accepted. However, text representations are prefered.
-  also allow inline feedback on the diagram itself.
+
+* Diagram examples
+
+asciiflow::
+
+  +––––––––––+     +–––––––––––+        +––––––––––+
+  | A        |     |  B        |        |  C       |
+  |          +–––––+           +––––––––+          |
+  +––––––––––+     +–––––––––––+        +––––––––––+
+
+blockdiag
+
+.. blockdiag::
+
+  blockdiag sample {
+    a -> b -> c;
+  }
+
+actdiag
+
+.. actdiag::
+
+   actdiag {
+     write -> convert -> image
+     lane user {
+       label = "User"
+       write [label = "Writing reST"];
+       image [label = "Get diagram IMAGE"];
+     }
+     lane actdiag {
+       convert [label = "Convert reST to Image"];
+     }
+   }
+
+nwdiag
+
+.. nwdiag::
+
+  nwdiag {
+    network dmz {
+      address = "210.x.x.x/24"
+
+      web01 [address = "210.x.x.1"];
+      web02 [address = "210.x.x.2"];
+    }
+    network internal {
+      address = "172.x.x.x/24";
+
+      web01 [address = "172.x.x.1"];
+      web02 [address = "172.x.x.2"];
+      db01;
+      db02;
+    }
+  }
+
+
+seqdiag
+
+.. seqdiag::
+
+  seqdiag {
+    browser  -> webserver [label = "GET /index.html"];
+    browser <-- webserver;
+    browser  -> webserver [label = "POST /blog/comment"];
+    webserver  -> database [label = "INSERT comment"];
+    webserver <-- database;
+    browser <-- webserver;
+  }
+
 
 
 Problem description

tests/test_titles.py

@@ -13,9 +13,23 @@
 import glob
 
 import docutils.core
+from docutils.parsers import rst
+from docutils.parsers.rst import directives
 import testtools
 
 
+class FakeDirective(rst.Directive):
+    has_content = True
+    def run(self):
+        return []
+
+
+directives.register_directive('seqdiag',  FakeDirective)
+directives.register_directive('blockdiag',  FakeDirective)
+directives.register_directive('nwdiag',  FakeDirective)
+directives.register_directive('actdiag',  FakeDirective)
+
+
 class TestTitles(testtools.TestCase):
     def _get_title(self, section_tree):
         section = {