L2SS-951: Finishing touch for documentation

.gitlab-ci.yml

-image: git.astron.nl:5000/lofar2.0/tango/lofar-device-base:l2ss-951
+image: git.astron.nl:5000/lofar2.0/tango/lofar-device-base:latest
 variables:
   GIT_SUBMODULE_STRATEGY: recursive
   PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

docker-compose/integration-test.yml

@@ -31,6 +31,11 @@ services:
       - --strict
       - --
       - tox -e integration
+# TODO(L2SS-992): Update me to use sitepackages once L2SS-992 is fixed.
+# sitepackages can be enabled for inside docker once pytango is installed from
+# requirements.txt (To ensure reliable builds / all environments same versions)
+# When run outside of docker, environment will be recreated if mismatched
+#      - tox --sitepackages -e integration
     command:
 #     Allow for arguments to be passed that wil be put after the entrypoint
 #     tox is configured to take these arguments as integration test directory

sbin/run_integration_test.sh

@@ -96,6 +96,10 @@ make stop elk
 
 # Run dummy integration test to install pytango in tox virtualenv without
 # the memory pressure of the ELK stack.
+# Alternatively this step can be avoided if we use:
+# `tox --sitepackages -e integration` for the integration docker container,
+# however, that does require creating a container specific integration job.
+# TODO(L2SS-992): Remove me and above documentation
 integration_test dummy
 
 make start elk

tangostationcontrol/tox.ini

@@ -6,7 +6,7 @@ skipsdist = True
 [testenv]
 usedevelop = True
 ; Python and tox variables are used to access modules and binaries instead of
-; directly. This is an artifact of having used sitepackages = true in the past.
+; directly. This makes the setup robust for using sitepackages=True.
 install_command = {envbindir}/pip3 install {opts} {packages}
 passenv = HOME
 setenv =
@@ -14,6 +14,8 @@ setenv =
    PYTHONWARNINGS=default::DeprecationWarning
 ; Share the same envdir with as many jobs as possible due to extensive time it
 ; takes to compile the pytango wheel, in addition to its large install size.
+; should the environment change (such as the Python version) the environment
+; will automatically be recreated.
 envdir = {toxworkdir}/testenv
 deps =
     -r{toxinidir}/requirements.txt
@@ -41,8 +43,6 @@ envdir = {toxworkdir}/testenvpy39
 envdir = {toxworkdir}/testenvpy310
 
 [testenv:integration]
-; Warning running integration tests will make changes to your docker system!
-; These tests should only be run by the integration-test docker container.
 allowlist_externals = echo
 passenv = TANGO_HOST
 setenv =