From 0a09001e5b74ef22bb89cf0ba3dbc4a9b47421a3 Mon Sep 17 00:00:00 2001
From: Tom Barron <tpb@dyncloud.net>
Date: Wed, 12 Apr 2017 18:00:54 -0400
Subject: [PATCH] Add support for blockdiag

and its family of diagrams [1]: blockdiag, actdiag, seqdiag,
and nwdiag.

These enable block, sequence, activity, and logical network
diagrams, defined in a simple text format, and with this patch
can be easily embedded in our specs.  For examples, see [2].

[1] http://blockdiag.com
[2] https://specs.openstack.org/openstack/neutron-specs/specs/juno-incubator/example.html

Change-Id: I999d8f5211266c4ce6d991ff92fe73e3843b5596
---
 doc/source/conf.py |  4 +++
 requirements.txt   |  8 +++++
 specs/template.rst | 89 ++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 94 insertions(+), 7 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1e22ff3..b8c2628 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -24,6 +24,10 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.graphviz',
+    'sphinxcontrib.blockdiag',
+    'sphinxcontrib.actdiag',
+    'sphinxcontrib.seqdiag',
+    'sphinxcontrib.nwdiag',
     'oslosphinx',
     # TODO(tbarron): re-enable yasfb after
     # https://github.com/sphinxcontrib/yasfb/commit/62d18c66835320af4a71fb088cb502041478fb16
diff --git a/requirements.txt b/requirements.txt
index 2022115..bb52422 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,5 +1,13 @@
 pbr>=2.0.0
 
+actdiag
+blockdiag
+nwdiag
 oslosphinx>=4.7.0
+seqdiag
 sphinx>=1.5.1
+sphinxcontrib-actdiag
+sphinxcontrib-blockdiag # BSD
+sphinxcontrib-nwdiag
+sphinxcontrib-seqdiag # BSD
 yasfb>=0.6.1
diff --git a/specs/template.rst b/specs/template.rst
index dc4bc5d..378de2c 100644
--- a/specs/template.rst
+++ b/specs/template.rst
@@ -33,13 +33,6 @@ Some notes about using this template:
 * To test out your formatting, build the docs using tox, or see:
   https://www.siafoo.net/reST.xml
 
-* If you would like to provide a diagram with your spec, ascii diagrams are
-  required.  http://asciiflow.com/ is a very nice tool to assist with making
-  ascii diagrams.  The reason for this is that the tool used to review specs is
-  based purely on plain text.  Plain text will allow review to proceed without
-  having to look at additional files which can not be viewed in gerrit.  It
-  will also allow inline feedback on the diagram itself.
-
 * If your specification proposes any changes to the Manila REST API such
   as changing parameters which can be returned or accepted, or even
   the semantics of what happens when a client calls into the API, then
@@ -47,6 +40,83 @@ Some notes about using this template:
   the APIImpact flag can be found with the following query:
   https://review.openstack.org/#/q/status:open+project:openstack/manila-specs+message:apiimpact,n,z
 
+* If you would like to provide a diagram with your spec, text
+  representations are preferred.  acsiiflow `[1]`_ and blockdiag `[2]`_
+  are good tools to assist with this.  Text representations are
+  preferred because the tool used to review specs is based
+  purely on plain text.  Plain text will allow review to proceed
+  without having to look at additional files which can not be viewed
+  in gerrit.  It will 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
 ===================
@@ -346,3 +416,8 @@ references are unavailable. Examples of what you could include are:
 * Related specifications as appropriate (e.g. link to any vendor documentation)
 
 * Anything else you feel it is worthwhile to refer to
+
+Diagram Tool References
+-----------------------
+* _`[1]` http://asciiflow.com
+* _`[2]` http://blockdiag.com