Add sphinx plantUML pluging

This patch enables the sphinx PlantUML extension. As PlantUML is often
used in Tacker documents, authors of specs can re-use diagrams when
they write user guides with small revising.

To build plantUML with a sphinx PlantUML extension:
- Updated conf.py
- Updated requirements
- Added plantuml.jar

To use the sphinx PlantUML extension in Zuul jobs:
- Added bindep [1][2] to install graphviz
- Added pre.yaml to install java [3]
- Updated setup.cfg (this is necessary to place more than two
  directories at the project root)

Others:
- Added examples to 2023.2/placeholder.rst and template.rst

[1] https://github.com/openstack/cinder-specs/blob/master/bindep.txt
[2] https://docs.opendev.org/opendev/bindep/latest/readme.html
[3] https://opendev.org/zuul/zuul-jobs/src/branch/master/roles/ensure-java

Change-Id: I72c2c7887ceba4734b367f7e5bc78921eb0ab0a1

.zuul.yaml

@@ -1,9 +1,14 @@
 - project:
-    templates:
-      - openstack-specs-jobs
     check:
       jobs:
+        - openstack-tacker-tox-docs
         - openstack-tox-pep8
     gate:
       jobs:
+        - openstack-tacker-tox-docs
         - openstack-tox-pep8
+
+- job:
+    name: openstack-tacker-tox-docs
+    parent: openstack-tox-docs
+    pre-run: playbooks/pre.yaml

README.rst

@@ -44,10 +44,15 @@ For more information about working with gerrit, see::
   https://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 To validate that the specification is syntactically correct (i.e. get more
-confidence in the Jenkins result), please execute the following command::
+confidence in the Zuul result), please execute the following command::
 
   $ tox
 
+Note that you need to install Java such as openjdk_ in advance to run ``tox``
+as the plantUML which depends on Java is used inside some specs.
+
 After running ``tox``, the documentation will be available for viewing in HTML
 format in the ``doc/build/`` directory. Please do not checkin the generated
 HTML files as a part of your commit.
+
+.. _openjdk: https://openjdk.org/install/

bindep.txt

@@ -0,0 +1 @@
+graphviz

doc/requirements.txt

@@ -7,3 +7,4 @@ sphinxcontrib-actdiag # BSD
 sphinxcontrib-blockdiag # BSD
 sphinxcontrib-nwdiag # BSD
 sphinxcontrib-seqdiag # BSD
+sphinxcontrib-plantuml # BSD

doc/source/conf.py

@@ -12,6 +12,7 @@
 # serve to show the default.
 
 import datetime
+import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -32,6 +33,7 @@ extensions = [
               'sphinxcontrib.actdiag',
               'sphinxcontrib.seqdiag',
               'sphinxcontrib.nwdiag',
+              'sphinxcontrib.plantuml',
               'openstackdocstheme',
              ]
 
@@ -233,3 +235,5 @@ openstackdocs_repo_name = 'openstack/tacker-specs'
 openstackdocs_auto_name = False
 openstackdocs_bug_project = 'tacker'
 openstackdocs_bug_tag = 'doc'
+
+plantuml = f'java -jar {os.path.abspath(".")}/../../tools/plantuml.jar'

playbooks/pre.yaml

@@ -0,0 +1,3 @@
+- hosts: all
+  roles:
+    - ensure-java

setup.cfg

@@ -10,3 +10,6 @@ classifier =
     Intended Audience :: Developers
     License :: OSI Approved :: Apache Software License
     Operating System :: POSIX :: Linux
+[files]
+packages =
+    specs

specs/2023.2/placeholder.rst

@@ -30,6 +30,17 @@ Proposed change
 
 Add this file. Please remove later when the another spec is approved.
 
+.. uml::
+
+  @startuml
+
+  [First component]
+  [Another component] as Comp2
+  component Comp3
+  component [Last\ncomponent] as Comp4
+
+  @enduml
+
 Alternatives
 ------------
 

specs/template.rst

@@ -110,6 +110,19 @@ seqdiag
   }
 
 
+* PlantUML examples
+
+.. uml::
+
+  @startuml
+
+  [First component]
+  [Another component] as Comp2
+  component Comp3
+  component [Last\ncomponent] as Comp4
+
+  @enduml
+
 
 Problem description
 ===================