[MCCS-519] PlantUML / RTD support

Makefile

@@ -18,7 +18,6 @@ SHELL = /bin/bash
 DOCKER_REGISTRY_USER:=ska-telescope
 PROJECT = ska_tango_base
 IMAGE_FOR_DIAGRAMS = nexus.engageska-portugal.pt/ska-docker/ska-python-buildenv:9.3.3.1
-IMAGE_FOR_DOCS = sphinxdoc/sphinx:latest
 #
 # include makefile to pick up the standard Make targets, e.g., 'make build'
 # build, 'make push' docker push procedure, etc. The other Make targets
@@ -57,12 +56,8 @@ generate-diagrams-in-docker-internals:  ## Generate state machine diagrams (with
 	ls -lo /diagrams/docs/source/images/
 
 docs-in-docker: ## Generate docs inside a container
-	@docker run --rm -v $(PWD):/project $(IMAGE_FOR_DOCS) bash -c "cd /project && make docs-in-docker-internals"
-
-docs-in-docker-internals:  ## Generate docs (within a container!)
-	test -f /.dockerenv  # ensure running in docker container
-	python3 -m pip install -r /project/docs/requirements.txt
-	cd /project/docs && make clean && make html
+	@docker build -t ska_tango_base_docs_builder  . -f docs/Dockerfile
+	@docker run --rm -v $(PWD):/project --user $(id -u):$(id -g) ska_tango_base_docs_builder
 
 help:  ## show this help.
 	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

docs/Dockerfile

+FROM readthedocs/build:latest
+
+COPY docs/requirements.txt .
+RUN python3 -m pip install --exists-action=w --no-cache-dir --disable-pip-version-check -r requirements.txt
+
+ENTRYPOINT python3 -m sphinx -T -E -b html -d project/docs/build/doctrees project/docs/source project/docs/build/html

docs/requirements.txt

 Sphinx >= 3.5.0
 sphinx-rtd-theme >= 0.4.3
+sphinxcontrib-plantuml

docs/source/State_Machine.rst

@@ -39,10 +39,8 @@ The admin mode state machine allows for
 
 Diagrams of the admin mode state machine are shown below.
 
-.. figure:: images/AdminModeStateMachine.png
-  :alt: Diagram of the admin mode state machine, as designed
-
-  Diagram of the admin mode state machine, as designed
+.. uml:: adminMode_state_machine.uml
+  :caption: Diagram of the admin mode state machine, as designed
 
 .. figure:: images/AdminModeStateMachine_autogenerated.png
   :alt: Diagram of the admin mode state machine, as implemented

docs/source/adminMode_state_machine.uml

+ONLINE --> ONLINE
+ONLINE <-right-> MAINTENANCE
+ONLINE <-down-> OFFLINE
+MAINTENANCE -> MAINTENANCE
+MAINTENANCE <-down-> OFFLINE
+OFFLINE -> OFFLINE
+OFFLINE <-down->NOT_FITTED
+OFFLINE <-down->RESERVED
+NOT_FITTED -> NOT_FITTED
+NOT_FITTED <-right->RESERVED
+RESERVED -> RESERVED

docs/source/conf.py

@@ -100,6 +100,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.plantuml'
 ]
 
 # Add any paths that contain templates here, relative to this directory.