L2SS-951: Update tox.ini documentation

tangostationcontrol/tox.ini

@@ -5,21 +5,15 @@ skipsdist = True
 
 [testenv]
 usedevelop = True
-; Module access is a bit of an ugly hack. This is due to testenv inheritance
-; with sitepackages = True`, meaning that global packages can be accessed by the
-; tox environment. Our tango images already have several dependencies system
-; wide installed, however, the system wide installation will never look inside
-; tox its virtualenv for packages. So accessing stestr and others fail.. We
-; can't remove `sitepackages = True` either as we need access to tango and
-; installing this package is non-trivial. The solution is to prevent calling
-; binaries directly and utilizing python and tox variables to resolve the
-; requested module.
-; sitepackages = 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.
 install_command = {envbindir}/pip3 install {opts} {packages}
 passenv = HOME
 setenv =
    VIRTUAL_ENV={envdir}
    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.
 envdir = {toxworkdir}/testenv
 deps =
     -r{toxinidir}/requirements.txt
@@ -32,6 +26,8 @@ commands =
     {envpython} -m stestr --version
     {envpython} -m stestr run {posargs}
 
+; We can't detect the current Python version for an environment dynamically
+; so each Python version specific job needs its own envdir.
 [testenv:py37]
 envdir = {toxworkdir}/testenvpy37