From 53af4b0f385c13a58758e6e530cba0c1efc8925a Mon Sep 17 00:00:00 2001
From: lukken <lukken@astron.nl>
Date: Wed, 5 Jan 2022 10:06:47 +0000
Subject: [PATCH] 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 | 28 ++++++++++--------
docs/Makefile | 20 -------------
docs/README.md | 9 ------
tangostationcontrol/docs/README.md | 8 +++++
.../docs/docs-requirements.txt | 2 ++
.../docs}/source/conf.py | 6 +++-
.../docs}/source/configure_station.rst | 0
.../docs}/source/developer.rst | 6 ++--
.../docs}/source/devices/beam.rst | 0
.../docs}/source/devices/boot.rst | 0
.../docs}/source/devices/configure.rst | 0
.../docs}/source/devices/docker.rst | 0
.../docs}/source/devices/recv.rst | 0
.../docs}/source/devices/sdp.rst | 0
.../docs}/source/devices/sst-xst.rst | 0
.../docs}/source/devices/using.rst | 0
.../docs}/source/faq.rst | 0
.../docs}/source/index.rst | 0
.../docs}/source/installation.rst | 0
.../docs}/source/interfaces/control.rst | 2 +-
.../docs}/source/interfaces/elk_last_hour.png | Bin
.../source/interfaces/elk_log_fields.png | Bin
.../source/interfaces/grafana_dashboard_1.png | Bin
.../source/interfaces/grafana_dashboard_2.png | Bin
.../interfaces/jupyter_basic_example.png | Bin
.../docs}/source/interfaces/logs.rst | 0
.../docs}/source/interfaces/monitoring.rst | 0
.../docs}/source/interfaces/overview.rst | 0
.../docs}/source/signal_chain.rst | 0
.../docs/source/static/css/custom.css | 4 +++
tangostationcontrol/requirements.txt | 2 +-
tangostationcontrol/setup-requirements.txt | 1 +
tangostationcontrol/tox.ini | 10 ++++++-
33 files changed, 49 insertions(+), 49 deletions(-)
delete mode 100644 docs/Makefile
delete mode 100644 docs/README.md
create mode 100644 tangostationcontrol/docs/README.md
create mode 100644 tangostationcontrol/docs/docs-requirements.txt
rename {docs => tangostationcontrol/docs}/source/conf.py (96%)
rename {docs => tangostationcontrol/docs}/source/configure_station.rst (100%)
rename {docs => tangostationcontrol/docs}/source/developer.rst (96%)
rename {docs => tangostationcontrol/docs}/source/devices/beam.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/boot.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/configure.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/docker.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/recv.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/sdp.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/sst-xst.rst (100%)
rename {docs => tangostationcontrol/docs}/source/devices/using.rst (100%)
rename {docs => tangostationcontrol/docs}/source/faq.rst (100%)
rename {docs => tangostationcontrol/docs}/source/index.rst (100%)
rename {docs => tangostationcontrol/docs}/source/installation.rst (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/control.rst (96%)
rename {docs => tangostationcontrol/docs}/source/interfaces/elk_last_hour.png (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/elk_log_fields.png (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/grafana_dashboard_1.png (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/grafana_dashboard_2.png (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/jupyter_basic_example.png (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/logs.rst (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/monitoring.rst (100%)
rename {docs => tangostationcontrol/docs}/source/interfaces/overview.rst (100%)
rename {docs => tangostationcontrol/docs}/source/signal_chain.rst (100%)
create mode 100644 tangostationcontrol/docs/source/static/css/custom.css
create mode 100644 tangostationcontrol/setup-requirements.txt
diff --git a/.gitignore b/.gitignore
index 6841e3ee2..6244a43b4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,20 +1,22 @@
-**/.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
diff --git a/docs/Makefile b/docs/Makefile
deleted file mode 100644
index d0c3cbf10..000000000
--- a/docs/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# 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)
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index d49db9ded..000000000
--- a/docs/README.md
+++ /dev/null
@@ -1,9 +0,0 @@
-To build the sphinx documentation, run:
-
-```
-pip3 install sphinx sphinx-rtd-theme
-
-make html
-```
-
-After which the documentation will be available in html format in the `build/html` directory.
diff --git a/tangostationcontrol/docs/README.md b/tangostationcontrol/docs/README.md
new file mode 100644
index 000000000..9e515e358
--- /dev/null
+++ b/tangostationcontrol/docs/README.md
@@ -0,0 +1,8 @@
+The sphinx documentation is build through tox which can be called from
+the parent directory using:
+
+```
+tox -e docs
+```
+
+After which the documentation will be available in html format in the `build/html` directory.
diff --git a/tangostationcontrol/docs/docs-requirements.txt b/tangostationcontrol/docs/docs-requirements.txt
new file mode 100644
index 000000000..689980c4d
--- /dev/null
+++ b/tangostationcontrol/docs/docs-requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=4.3.2 # BSD
+sphinx-rtd-theme>=1.0.0 # MIT
\ No newline at end of file
diff --git a/docs/source/conf.py b/tangostationcontrol/docs/source/conf.py
similarity index 96%
rename from docs/source/conf.py
rename to tangostationcontrol/docs/source/conf.py
index cf6f1dea2..9ab504856 100644
--- a/docs/source/conf.py
+++ b/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',
+]
diff --git a/docs/source/configure_station.rst b/tangostationcontrol/docs/source/configure_station.rst
similarity index 100%
rename from docs/source/configure_station.rst
rename to tangostationcontrol/docs/source/configure_station.rst
diff --git a/docs/source/developer.rst b/tangostationcontrol/docs/source/developer.rst
similarity index 96%
rename from docs/source/developer.rst
rename to tangostationcontrol/docs/source/developer.rst
index e2c36f83c..6e4cf0123 100644
--- a/docs/source/developer.rst
+++ b/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:
diff --git a/docs/source/devices/beam.rst b/tangostationcontrol/docs/source/devices/beam.rst
similarity index 100%
rename from docs/source/devices/beam.rst
rename to tangostationcontrol/docs/source/devices/beam.rst
diff --git a/docs/source/devices/boot.rst b/tangostationcontrol/docs/source/devices/boot.rst
similarity index 100%
rename from docs/source/devices/boot.rst
rename to tangostationcontrol/docs/source/devices/boot.rst
diff --git a/docs/source/devices/configure.rst b/tangostationcontrol/docs/source/devices/configure.rst
similarity index 100%
rename from docs/source/devices/configure.rst
rename to tangostationcontrol/docs/source/devices/configure.rst
diff --git a/docs/source/devices/docker.rst b/tangostationcontrol/docs/source/devices/docker.rst
similarity index 100%
rename from docs/source/devices/docker.rst
rename to tangostationcontrol/docs/source/devices/docker.rst
diff --git a/docs/source/devices/recv.rst b/tangostationcontrol/docs/source/devices/recv.rst
similarity index 100%
rename from docs/source/devices/recv.rst
rename to tangostationcontrol/docs/source/devices/recv.rst
diff --git a/docs/source/devices/sdp.rst b/tangostationcontrol/docs/source/devices/sdp.rst
similarity index 100%
rename from docs/source/devices/sdp.rst
rename to tangostationcontrol/docs/source/devices/sdp.rst
diff --git a/docs/source/devices/sst-xst.rst b/tangostationcontrol/docs/source/devices/sst-xst.rst
similarity index 100%
rename from docs/source/devices/sst-xst.rst
rename to tangostationcontrol/docs/source/devices/sst-xst.rst
diff --git a/docs/source/devices/using.rst b/tangostationcontrol/docs/source/devices/using.rst
similarity index 100%
rename from docs/source/devices/using.rst
rename to tangostationcontrol/docs/source/devices/using.rst
diff --git a/docs/source/faq.rst b/tangostationcontrol/docs/source/faq.rst
similarity index 100%
rename from docs/source/faq.rst
rename to tangostationcontrol/docs/source/faq.rst
diff --git a/docs/source/index.rst b/tangostationcontrol/docs/source/index.rst
similarity index 100%
rename from docs/source/index.rst
rename to tangostationcontrol/docs/source/index.rst
diff --git a/docs/source/installation.rst b/tangostationcontrol/docs/source/installation.rst
similarity index 100%
rename from docs/source/installation.rst
rename to tangostationcontrol/docs/source/installation.rst
diff --git a/docs/source/interfaces/control.rst b/tangostationcontrol/docs/source/interfaces/control.rst
similarity index 96%
rename from docs/source/interfaces/control.rst
rename to tangostationcontrol/docs/source/interfaces/control.rst
index adb577552..4dac94eb9 100644
--- a/docs/source/interfaces/control.rst
+++ b/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.
diff --git a/docs/source/interfaces/elk_last_hour.png b/tangostationcontrol/docs/source/interfaces/elk_last_hour.png
similarity index 100%
rename from docs/source/interfaces/elk_last_hour.png
rename to tangostationcontrol/docs/source/interfaces/elk_last_hour.png
diff --git a/docs/source/interfaces/elk_log_fields.png b/tangostationcontrol/docs/source/interfaces/elk_log_fields.png
similarity index 100%
rename from docs/source/interfaces/elk_log_fields.png
rename to tangostationcontrol/docs/source/interfaces/elk_log_fields.png
diff --git a/docs/source/interfaces/grafana_dashboard_1.png b/tangostationcontrol/docs/source/interfaces/grafana_dashboard_1.png
similarity index 100%
rename from docs/source/interfaces/grafana_dashboard_1.png
rename to tangostationcontrol/docs/source/interfaces/grafana_dashboard_1.png
diff --git a/docs/source/interfaces/grafana_dashboard_2.png b/tangostationcontrol/docs/source/interfaces/grafana_dashboard_2.png
similarity index 100%
rename from docs/source/interfaces/grafana_dashboard_2.png
rename to tangostationcontrol/docs/source/interfaces/grafana_dashboard_2.png
diff --git a/docs/source/interfaces/jupyter_basic_example.png b/tangostationcontrol/docs/source/interfaces/jupyter_basic_example.png
similarity index 100%
rename from docs/source/interfaces/jupyter_basic_example.png
rename to tangostationcontrol/docs/source/interfaces/jupyter_basic_example.png
diff --git a/docs/source/interfaces/logs.rst b/tangostationcontrol/docs/source/interfaces/logs.rst
similarity index 100%
rename from docs/source/interfaces/logs.rst
rename to tangostationcontrol/docs/source/interfaces/logs.rst
diff --git a/docs/source/interfaces/monitoring.rst b/tangostationcontrol/docs/source/interfaces/monitoring.rst
similarity index 100%
rename from docs/source/interfaces/monitoring.rst
rename to tangostationcontrol/docs/source/interfaces/monitoring.rst
diff --git a/docs/source/interfaces/overview.rst b/tangostationcontrol/docs/source/interfaces/overview.rst
similarity index 100%
rename from docs/source/interfaces/overview.rst
rename to tangostationcontrol/docs/source/interfaces/overview.rst
diff --git a/docs/source/signal_chain.rst b/tangostationcontrol/docs/source/signal_chain.rst
similarity index 100%
rename from docs/source/signal_chain.rst
rename to tangostationcontrol/docs/source/signal_chain.rst
diff --git a/tangostationcontrol/docs/source/static/css/custom.css b/tangostationcontrol/docs/source/static/css/custom.css
new file mode 100644
index 000000000..74265d28e
--- /dev/null
+++ b/tangostationcontrol/docs/source/static/css/custom.css
@@ -0,0 +1,4 @@
+
+.rst-content code, .rst-content tt, code {
+ white-space: break-spaces;
+}
\ No newline at end of file
diff --git a/tangostationcontrol/requirements.txt b/tangostationcontrol/requirements.txt
index f2d3743cd..bda60f72f 100644
--- a/tangostationcontrol/requirements.txt
+++ b/tangostationcontrol/requirements.txt
@@ -7,7 +7,7 @@ PyMySQL[rsa] >= 1.0.2 # MIT
psycopg2-binary >= 2.9.2 #LGPL
sqlalchemy >= 1.4.26 #MIT
snmp >= 0.1.7 # GPL3
-h5py >= 3.5.0 # BSD
+h5py >= 3.1.0 # BSD
psutil >= 5.8.0 # BSD
docker >= 5.0.3 # Apache 2
python-logstash-async >= 2.3.0 # MIT
diff --git a/tangostationcontrol/setup-requirements.txt b/tangostationcontrol/setup-requirements.txt
new file mode 100644
index 000000000..5d5b72b81
--- /dev/null
+++ b/tangostationcontrol/setup-requirements.txt
@@ -0,0 +1 @@
+GitPython >= 3.1.20 # BSD
\ No newline at end of file
diff --git a/tangostationcontrol/tox.ini b/tangostationcontrol/tox.ini
index 69782d5e3..5b286b102 100644
--- a/tangostationcontrol/tox.ini
+++ b/tangostationcontrol/tox.ini
@@ -1,6 +1,6 @@
[tox]
minversion = 2.0
-envlist = py36,py37,py38,py39,pep8
+envlist = py36,py37,py38,py39,py310,pep8
skipsdist = True
[testenv]
@@ -14,6 +14,7 @@ setenv =
OS_STDERR_CAPTURE=1
OS_TEST_TIMEOUT=60
deps =
+ -r{toxinidir}/setup-requirements.txt
-r{toxinidir}/test-requirements.txt
-r{toxinidir}/../docker-compose/lofar-device-base/lofar-requirements.txt
commands = stestr run {posargs}
@@ -41,6 +42,13 @@ commands =
commands =
bandit -r devices/ -n5 -ll -s B104
+[testenv:docs]
+deps =
+ -r{toxinidir}/setup-requirements.txt
+ -r{toxinidir}/docs/docs-requirements.txt
+commands =
+ sphinx-build -W -b html docs/source docs/build/html
+
[flake8]
filename = *.py,.stestr.conf,.txt
select = W292,B601,B602,T100,M001
--
GitLab