Embed UML generated diagrams into docs, fix docs build

Remove manual generation of UML diagrams; they will be built by Sphinx
itself.

Require to install PlantUML and Graphviz via bindep in
openstack-tox-docs job; ReadTheDocs service already has both PlantUML
and Graphviz installed for documentation builds.

Change-Id: I21ab124a80e7768bc9edd891b975b4e0f8a6e50d
Story: 2004747

Makefile

@@ -94,6 +94,8 @@ clean:
 	rm -rf build
 	helm delete helm-template ||:
 	rm -rf doc/build
+	# Don't remove .placeholder from doc/source/_static/
+	rm -rf doc/api doc/source/_static/* doc/source/contributor/api
 
 .PHONY: docs
 docs: clean build_docs

bindep.txt

@@ -0,0 +1,6 @@
+# This file contains runtime (non-python) dependencies
+# More info at: https://docs.openstack.org/infra/bindep/readme.html
+
+# PlantUML is used for documentation builds, graphviz is it's soft  dependancy
+plantuml
+graphviz

doc/requirements.txt

@@ -6,6 +6,7 @@ sphinx_rtd_theme
 reno>=2.5.0 # Apache-2.0
 plantuml
 sphinxcontrib-apidoc>=0.2.0  # BSD
+sphinxcontrib-plantuml
 
 # NOTE(felipemonteiro): Required by RTD to make oslo.policy and
 # oslo.config sample generation work.

doc/source/conf.py

@@ -40,6 +40,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinxcontrib.apidoc',
+    'sphinxcontrib.plantuml',
     'oslo_config.sphinxconfiggen',
     'oslo_policy.sphinxpolicygen',
     # NOTE(fmontei): This is here so that readthedocs can publish releasenotes

doc/source/contributor/developer-overview.rst

@@ -26,7 +26,7 @@ Airship components.
 Architecture
 ============
 
-.. image:: ../images/architecture.png
+.. uml:: ../diagrams/architecture.uml
    :alt: High level architecture of Deckhand
 
 From a high-level perspective, Deckhand consists of a RESTful API, a document
@@ -41,7 +41,7 @@ Deckhand uses Barbican to securely storage sensitive document data.
 `Pegleg <https://airship-pegleg.readthedocs.io/>`_ in effect provides
 Deckhand with a CLI, which facilitates communication with Deckhand.
 
-.. image:: ../images/architecture-pegleg.png
+.. uml:: ../diagrams/architecture-pegleg.uml
    :alt: High level architecture of Deckhand + Pegleg
 
 Components

tools/build-docs.sh

@@ -5,11 +5,6 @@
 
 set -ex
 
-# Generate architectural diagrams.
-mkdir -p doc/source/images
-python -m plantuml doc/source/diagrams/*.uml
-mv doc/source/diagrams/*.png doc/source/images
-
 # Generate documentation.
 rm -rf doc/build doc/source/contributor/api/ releasenotes/build
 sphinx-apidoc -o doc/api deckhand