doc: Document tox usage for developers

Fixes: https://tracker.ceph.com/issues/40363
Signed-off-by: Stephan Müller <smueller@suse.com>

diff --git a/doc/dev/developer_guide/index.rst b/doc/dev/developer_guide/index.rst
index ceb9a17fb2661ffcb8ce890cd94bd71696b270c3..419a361f9af2b31bb7cf55fe6697702b68cdecca 100644 (file)
--- a/doc/dev/developer_guide/index.rst
+++ b/doc/dev/developer_guide/index.rst
@@ -790,6 +790,44 @@ the `cram task`_.
 .. _`cram`: https://bitheap.org/cram/
 .. _`cram task`: https://github.com/ceph/ceph/blob/master/qa/tasks/cram.py
 
+Tox based testing of python modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most python modules can be found under ``./src/pybind/``.
+
+Many modules use **tox** to run their unit tests.
+**tox** itself is a generic virtualenv management and test command line tool.
+
+To find out quickly if tox can be run you can either just try to run ``tox`` or find out if a
+``tox.ini`` exists.
+
+Currently the following modules use tox:
+
+- Ansible (``./src/pybind/mgr/ansible``)
+- Insights (``./src/pybind/mgr/insights``)
+- Orchestrator cli (``./src/pybind/mgr/orchestrator_cli``)
+- Manager core (``./src/pybind/mgr``)
+- Dashboard (``./src/pybind/mgr/dashboard``)
+- Python common (``./src/python-common/tox.ini``)
+
+Most tox configuration support multiple environments and tasks. You can see which environments and
+tasks are supported by looking into the ``tox.ini`` file to see what ``envlist`` is assigned.
+To run **tox**, just execute ``tox`` in the directory where ``tox.ini`` lies.
+Without any specified environments ``-e $env1,$env2``, all environments will be run.
+Jenkins will run ``tox`` by executing ``run_tox.sh`` which lies under ``./src/script``.
+
+Here some examples from ceph dashboard on how to specify different environments and run options::
+
+  ## Run Python 2+3 tests+lint commands:
+  $ tox -e py27,py3,lint,check
+
+  ## Run Python 3 tests+lint commands:
+  $ tox -e py3,lint,check
+
+  ## To run it like Jenkins would do
+  $ ../../../script/run_tox.sh --tox-env py27,py3,lint,check
+  $ ../../../script/run_tox.sh --tox-env py3,lint,check
+
 Unit test caveats
 -----------------