openstack
/
manila-specs
Code Issues Proposed changes

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
This commit is contained in:
Tom Barron 2017-04-12 18:00:54 -04:00
parent 3c669be677
commit 0a09001e5b
3 changed files with 94 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/conf.py
View File

@ -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

8
requirements.txt
View File

@ -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

89
specs/template.rst
View File

@ -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