From: Stephan Müller <smueller@suse.com>
Date: Thu, 5 Sep 2019 13:33:20 +0000 (+0200)
Subject: doc: Document tox usage for developers
X-Git-Tag: v15.1.0~942^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=f2c913d47ec63f0007a358fb5c5d32ad3dd741d3;p=ceph.git

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 ceb9a17fb266..419a361f9af2 100644
--- 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
 -----------------