Add a system overview section on the landing page #867

changelog/867.doc.rst

@@ -0,0 +1,2 @@
+Add a system overview section on the index page that explains briefly how tox works -
+by :user:`gaborbernat`.

doc/_static/custom.css

@@ -20,6 +20,15 @@ ul > li > p {
 
 }
 
+ol > li {
+    text-align: justify;
+}
+
+ol > li > p {
+    margin-bottom: 0;
+
+}
+
 div.body code.descclassname {
     display: none
 }

doc/index.rst

@@ -55,6 +55,71 @@ you'll note that it runs much faster because it keeps track of virtualenv detail
 and will not recreate or re-install dependencies.  You also might want to
 checkout :doc:`examples` to get some more ideas.
 
+System overview
+---------------
+
+.. figure:: img/tox_flow.png
+   :align: center
+   :width: 800px
+
+   tox workflow diagram
+
+..
+    The above image raw can be found and edited by using the toxdevorg Google role account under
+    https://www.lucidchart.com/documents/edit/5d921f32-f2e1-4618-a265-7f9e30503dc6/0
+
+tox roughly follows the following phases:
+
+1. **configuration:** load ``tox.ini`` and merge it with options from the command line and the
+   operating system environment variables.
+2. **packaging** (optional): create a source distribution of the current project by invoking
+
+   .. code-block:: bash
+
+      python setup.py sdist
+
+   Note that for this operation the same Python environment will be used as the one tox is
+   installed into (therefore you need to make sure that it contains your build dependencies).
+   Skip this step for application projects that don't have a ``setup.py``.
+
+3. **environment** - for each tox environment (e.g. ``py27``, ``py36``) do:
+
+    1. **environment creation**: create a fresh environment, by default virtualenv_ is used. tox will
+    automatically try to discover a valid Python interpreter version by using the environment name
+    (e.g. ``py27`` means Python 2.7 and the ``basepython`` configuration value) and the current
+    operating system ``PATH`` value. This is created at first run only to be re-used at subsequent
+    runs. If certain aspects of the project change, a re-creation of the environment is
+    automatically triggered. To force the recreation tox can be invoked with ``-r``/``--recreate``.
+
+    2. **install** (optional): install the environment dependencies specified inside the
+    :confval:`deps` configuration section, and then the earlier packaged source distribution.
+    By default ``pip`` is used to install packages, however one can customise this via
+    :confval:`install_command`. Note ``pip`` will not update project dependencies (specified either
+    in the ``install_requires`` or the ``extras`` section of the ``setup.py``) if any version already
+    exists in the virtual environment; therefore we recommend to recreate your environments
+    whenever your project dependencies change.
+
+    3. **commands**: run the specified commands in the specified order. Whenever the exit code of
+    any of them is not zero stop, and mark the environment failed. Note, starting a command with a
+    single dash character means ignore exit code.
+
+6. **report** print out a report of outcomes for each tox environment:
+
+   .. code:: bash
+
+      ____________________ summary ____________________
+      py27: commands succeeded
+      ERROR:   py36: commands failed
+
+    Only if all environments ran successfully tox will return exit code ``0`` (success). In this
+    case you'll also see the message ``congratulations :)``.
+
+tox will take care of environment isolation for you: it will strip away all operating system
+environment variables not specified via :confval:`passenv`. Furthermore, it will also alter the
+``PATH`` variable so that your commands resolve first and foremost within the current active
+tox environment. In general all executables in the path are available in ``commands``, but tox will
+emit a warning if it was not explicitly allowed via :confval:`whitelist_external`.
+
 Current features
 -------------------