L2SS-556: Build sphinx documentation using toxs

This isolates the python packages and prevents them from having
to be installed system wide.

In addition it uses requirements files so we can appropriately
constrain the versions of individual packages used.

.gitignore

-**/.idea
-**/.DS_Store
-**/__pycache__
-**/*.pyc
 **/*.egg-info
-**/.tox
+**/*.pyc
+**/.DS_Store
+**/.eggs
+**/.idea
+**/.ipynb_checkpoints
+**/.project
+**/.pydevproject
+**/.settings/org.eclipse.core.resources.prefs
 **/.stestr
+**/.tox
+**/__pycache__
 **/AUTHORS
 **/ChangeLog
 **/env
+**/pending_log_messages.db
 **/vscode-server.tar
-**/.project
-**/.pydevproject
-**/.settings/org.eclipse.core.resources.prefs
-docs/build
-tangostationcontrol/dist
+
 tangostationcontrol/build
-**/.ipynb_checkpoints
-**/pending_log_messages.db
-**/.eggs
+tangostationcontrol/dist
+
+tangostationcontrol/docs/build

docs/Makefile

-# Minimal makefile for Sphinx documentation
-#
-
-# 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
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# 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/README.md → tangostationcontrol/docs/README.md

-To build the sphinx documentation, run:
+The sphinx documentation is build through tox which can be called from
+the parent directory using:
 
 ```
-pip3 install sphinx sphinx-rtd-theme
-
-make html
+tox -e docs
 ```
 
 After which the documentation will be available in html format in the `build/html` directory.

tangostationcontrol/docs/docs-requirements.txt

+sphinx>=4.3.2 # BSD
+sphinx-rtd-theme>=1.0.0 # MIT
\ No newline at end of file

docs/source/conf.py → tangostationcontrol/docs/source/conf.py

@@ -49,4 +49,8 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['static']
+
+html_css_files = [
+    'css/custom.css',
+]

docs/source/developer.rst → tangostationcontrol/docs/source/developer.rst

@@ -32,7 +32,7 @@ The Docker containers started use a *virtual network* to communicate among each
 
 The networks are defined in ``docker-compose/networks.yml``:
 
-.. literalinclude:: ../../docker-compose/networks.yml
+.. literalinclude:: ../../../docker-compose/networks.yml
 
 The ``$NETWORK_MODE`` defaults to ``tangonet`` in the ``docker-compose/Makefile``.
 
@@ -79,7 +79,7 @@ The ELK stack collects the logs from the containers, as well as any external pro
 
 We recommend making sure the contents of your log lines are parsed correctly, especially if logs are routed to the *Syslog* input. These configurations are stored in ``docker-compose/elk/logstash/conf.d``. An example: 
 
-.. literalinclude:: ../../docker-compose/elk/logstash/conf.d/22-parse-tango-rest.conf
+.. literalinclude:: ../../../docker-compose/elk/logstash/conf.d/22-parse-tango-rest.conf
 
 Log from Python
 `````````````````
@@ -91,7 +91,7 @@ Log from Docker
 
 Not all Docker containers run our Python programs, and can forward the logs themselves. For those, we use the ``syslog`` log driver in Docker. Extend the ``docker compose`` files with:
 
-.. literalinclude:: ../../docker-compose/rest.yml
+.. literalinclude:: ../../../docker-compose/rest.yml
    :start-at: logging:
    :end-before: restart:
 

docs/source/interfaces/control.rst → tangostationcontrol/docs/source/interfaces/control.rst

@@ -12,7 +12,7 @@ The station offers Juypyter notebooks On http://localhost:8888, which allow one
 
 The notebooks provide some predefined variables, so you don't have to look them up:
 
-.. literalinclude:: ../../../docker-compose/jupyter/ipython-profiles/stationcontrol-jupyter/startup/01-devices.py
+.. literalinclude:: ../../../../docker-compose/jupyter/ipython-profiles/stationcontrol-jupyter/startup/01-devices.py
 
 Note: the Jupyter notebooks use enhancements from the ``itango`` suite, which provide tab completions, but also the ``Device`` alias for ``DeviceProxy`` as was used in the Python examples in the next section.