diff --git a/Makefile b/Makefile
index d120dd29d9eb7d08bef998acd77db6e8b69139e3..cf201f8e88087cc647c98ef98e33a134a1ad76ff 100644
--- a/Makefile
+++ b/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}'
diff --git a/docs/Dockerfile b/docs/Dockerfile
new file mode 100644
index 0000000000000000000000000000000000000000..b7ad9a0c7d755009e384e184b50d4a80895c0687
--- /dev/null
+++ b/docs/Dockerfile
@@ -0,0 +1,6 @@
+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
diff --git a/docs/requirements.txt b/docs/requirements.txt
index e4e2f8eab706cdd8accda951aa6180e50ca93c62..a1912774657061bdfb5d73f9a6e7b86a1300d985 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,3 @@
 Sphinx >= 3.5.0
 sphinx-rtd-theme >= 0.4.3
+sphinxcontrib-plantuml
diff --git a/docs/source/State_Machine.rst b/docs/source/State_Machine.rst
index ed542bfd920af67a90f41f6603ce0a9268758f92..b8133a507f0f3ffcdb6d5478db64b128a99b59db 100644
--- a/docs/source/State_Machine.rst
+++ b/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
diff --git a/docs/source/adminMode_state_machine.uml b/docs/source/adminMode_state_machine.uml
new file mode 100644
index 0000000000000000000000000000000000000000..24945b2c165137ea9f8da0e10fed1d868b864d77
--- /dev/null
+++ b/docs/source/adminMode_state_machine.uml
@@ -0,0 +1,11 @@
+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
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 361c6f7493eddae7dff276f55c9957e6636776f8..8871ddcafd1f0f288cb9a54914a3196a9002214c 100644
--- a/docs/source/conf.py
+++ b/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.
diff --git a/docs/source/images/AdminModeStateMachine.png b/docs/source/images/AdminModeStateMachine.png
deleted file mode 100644
index 6351a89cf21b929414bfdaa2ca37028d77a32591..0000000000000000000000000000000000000000
Binary files a/docs/source/images/AdminModeStateMachine.png and /dev/null differ