Merge branch 'improve-docs' into 'master'

Improve Sphinx documentation

See merge request ska-telescope/ska-tango-base!42

Makefile

@@ -18,6 +18,7 @@ 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
@@ -55,6 +56,14 @@ generate-diagrams-in-docker-internals:  ## Generate state machine diagrams (with
 	cd /diagrams/docs/source && python3 draw_state_machines.py
 	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
+
 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/Makefile

-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
 BUILDDIR      = build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SKA_TangoBase.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SKA_TangoBase.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/SKA_TangoBase"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SKA_TangoBase"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+.PHONY: help Makefile
 
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

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

docs/source/Commands.rst

 
-SKA Commands
+Commands
 ============================================
 
 .. toctree::

docs/source/CspSubElementMaster.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA CSP Sub-element Master
+CSP Sub-element Master
 ============================================
 This module implements a general Master device for a CSP Sub-element.
 
@@ -11,6 +11,10 @@ This module implements a general Master device for a CSP Sub-element.
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.csp_subelement_master
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.CspSubElementMaster
    :members:
    :undoc-members:

docs/source/CspSubElementObsDevice.rst

@@ -7,13 +7,17 @@
 
    <br />
 
-SKA CSP Sub-element ObsDevice
+CSP Sub-element ObsDevice
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.csp_subelement_obsdevice
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.CspSubElementObsDevice
    :members:
    :undoc-members:

docs/source/CspSubElementSubarray.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA CSP Sub-element Subarray
+CSP Sub-element Subarray
 ============================================
 This module implements a generic Subarray device for a CSP Sub-element.
 The scope of this module is to provide a uniform access to a CSP Sub-element
@@ -14,6 +14,10 @@ subarray from the CSP.LMC side.
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.csp_subelement_subarray
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.CspSubElementSubarray
    :members:
    :undoc-members:

docs/source/SKAAlarmHandler.rst

@@ -3,13 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA AlarmHandler
+Alarm Handler
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.alarm_handler_device
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.SKAAlarmHandler
    :members:
    :undoc-members:

docs/source/SKABaseDevice.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA BaseDevice
+Base Device
 ============================================
 
 .. toctree::
@@ -11,10 +11,16 @@ SKA BaseDevice
 
 .. automodule:: ska_tango_base.base_device
 
-.. autoclass:: ska_tango_base.DeviceStateModel
+Tango Device Class
+------------------
+
+.. autoclass:: ska_tango_base.SKABaseDevice
    :members:
    :undoc-members:
 
-.. autoclass:: ska_tango_base.SKABaseDevice
+Device State Model
+------------------
+
+.. autoclass:: ska_tango_base.DeviceStateModel
    :members:
    :undoc-members:

docs/source/SKACapability.rst

@@ -3,13 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA Capability
+Capability
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.capability_device
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.SKACapability
    :members:
    :undoc-members:

docs/source/SKALogger.rst

@@ -3,13 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA Logger
+Logger
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.logger_device
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.SKALogger
    :members:
    :undoc-members:

docs/source/SKAMaster.rst

@@ -3,13 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA Master
+Master
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.master_device
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.SKAMaster
    :members:
    :undoc-members:

docs/source/SKAObsDevice.rst

@@ -3,13 +3,24 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA ObsDevice
+Observation Device
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.obs_device
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.SKAObsDevice
    :members:
    :undoc-members:
+
+Device State Model
+------------------
+
+.. autoclass:: ska_tango_base.ObsDeviceStateModel
+   :members:
+   :undoc-members:
\ No newline at end of file

docs/source/SKASubarray.rst

@@ -3,13 +3,31 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA Subarray
+Subarray
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.subarray_device
+
+Device Class
+------------
+
 .. autoclass:: ska_tango_base.SKASubarray
    :members:
    :undoc-members:
+
+Device State Model
+------------------
+
+.. autoclass:: ska_tango_base.SKASubarrayStateModel
+   :members:
+   :undoc-members:
+
+Resource Manager
+----------------
+
+.. autoclass:: ska_tango_base.SKASubarrayResourceManager
+   :members:
+   :undoc-members:

docs/source/SKATelState.rst

@@ -3,13 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-SKA TelState
+Telescope State
 ============================================
 
 .. toctree::
    :maxdepth: 2
 
 .. automodule:: ska_tango_base.tel_state_device
+
+Tango Device Class
+------------------
+
 .. autoclass:: ska_tango_base.SKATelState
    :members:
    :undoc-members:

docs/source/State_Machine.rst

@@ -188,18 +188,7 @@ API
     :members:
     :undoc-members:
 
-.. autoclass:: OperationStateMachine
-    :members:
-
-.. autoclass:: AdminModeStateMachine
-    :members:
-
-.. autoclass:: ObservationStateMachine
-    :members:
 
 .. automodule:: ska_tango_base.csp_subelement_state_machine
     :members:
     :undoc-members:
-
-.. autoclass:: CspSubElementObsDeviceStateMachine
-    :members:

docs/source/_static/css/custom.css

+/*
+Following SKA brand guidelines colors are defined as
+
+SKA Sky Blue:    rgb(0, 174, 239)
+SKA Ocean Blue:  rgb(0, 84, 164)
+SKA Teal Blue:   rgb(0, 104, 138)
+SKA Burnt Sun:   rgb(236, 134, 35)
+SKA Earth Green: rgb(166, 206, 57)
+*/
+
+.wy-nav-side{
+        background-color: rgb(0, 84, 164);
+        color: white;
+}
+
+.wy-side-nav-search{
+        padding-top: 0px;
+        /*background-color: rgb(0, 174, 239);*/
+        background-color: rgb(0, 84, 164);
+        text-align: center;
+}
+
+.wy-menu-vertical p.caption{
+        color: rgb(236, 134, 35);
+}
+
+.wy-menu {
+        color: white;
+}
+
+.wy-menu-vertical a{
+  color: white;
+}
+
+.local-toc ul li a:hover {
+        background-color: rgb(0, 174, 239);
+}
+
+.wy-side-nav-search a{
+    padding-top: 0px;
+}
+
+.wy-side-nav-search a img.logo{
+	background-color: rgb(255, 255, 255);
+	border-bottom-left-radius: 6px;
+	border-bottom-right-radius: 6px;
+      padding-top: 40px;
+}
+
+.ska-logo, ska-logo:hover{
+	background-attachment: scroll;
+	background-clip: border-box;
+	background-color: rgb(255, 255, 255);
+	background-image: url("https://www.skatelescope.org/wp-content/themes/skatelescope.org-theme/img/img-logo3.png");
+	background-origin: padding-box;
+	background-position: 22px 35px;
+	background-position-x: 22px;
+	background-position-y: 35px;
+	background-repeat: no-repeat;
+	background-size: 153px 98px;
+	border-bottom-left-radius: 6px;
+	border-bottom-right-radius: 6px;
+	/*color: rgb(0, 86, 120);
+	float: left;
+	font-family: "Eurostile LT W01 Demi", sans-serif;
+	font-size: 44.8px;
+	font-weight: 400;
+	line-height: 60px;
+	list-style-image: none;
+	list-style-position: outside;
+	list-style-type: none;*/
+	margin-bottom: 0px;
+	margin-left: 0px;
+	margin-right: 0px;
+	margin-top: 0px;
+	width: 186px;
+	height: 135px;
+}