Browse Source

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
changes/57/635357/5
Roman Gorshunov 3 months ago
parent
commit
c81a88b963

+ 2
- 0
Makefile View File

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

+ 6
- 0
bindep.txt View File

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

+ 1
- 0
doc/requirements.txt View File

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

+ 1
- 0
doc/source/conf.py View File

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

+ 2
- 2
doc/source/contributor/developer-overview.rst View File

@@ -26,7 +26,7 @@ Airship components.
26 26
 Architecture
27 27
 ============
28 28
 
29
-.. image:: ../images/architecture.png
29
+.. uml:: ../diagrams/architecture.uml
30 30
    :alt: High level architecture of Deckhand
31 31
 
32 32
 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.
41 41
 `Pegleg <https://airship-pegleg.readthedocs.io/>`_ in effect provides
42 42
 Deckhand with a CLI, which facilitates communication with Deckhand.
43 43
 
44
-.. image:: ../images/architecture-pegleg.png
44
+.. uml:: ../diagrams/architecture-pegleg.uml
45 45
    :alt: High level architecture of Deckhand + Pegleg
46 46
 
47 47
 Components

BIN
doc/source/images/architecture-pegleg.png View File


BIN
doc/source/images/architecture.png View File


+ 0
- 5
tools/build-docs.sh View File

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

Loading…
Cancel
Save