Merged in jurko/tox/jurko/documentation-fixes (pull request #87)

doc/example/devenv.txt documentation update

2 files changed, 62 insertions, 45 deletions

diff --git a/doc/config.txt b/doc/config.txt
index 8eb8f3a..34b88af 100644
--- a/doc/config.txt
+++ b/doc/config.txt
@@ -80,7 +80,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     .. versionadded:: 1.6
 
-    **WARNING**: This setting is **EXPERIMENTAL** so use with care 
+    **WARNING**: This setting is **EXPERIMENTAL** so use with care
     and be ready to adapt your tox.ini's with post-1.6 tox releases.
 
     the ``install_command`` setting is used for installing packages into
@@ -94,12 +94,12 @@ Complete list of settings that you can put into ``testenv*`` sections:
     if you have configured it.
 
     **default**::
-    
+
         pip install --pre {opts} {packages}
-         
+
     **default on environments using python2.5**::
 
-        pip install {opts} {packages}`` 
+        pip install {opts} {packages}``
 
     this will use pip<1.4 which has no ``--pre`` option.  Note also
     that for python2.5 support you may need to install ssl and/or
@@ -109,7 +109,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     each line specifies a command name (in glob-style pattern format)
     which can be used in the ``commands`` section without triggering
-    a "not installed in virtualenv" warning.  Example: if you use the 
+    a "not installed in virtualenv" warning.  Example: if you use the
     unix ``make`` for running tests you can list ``whitelist_externals=make``
     or ``whitelist_externals=/usr/bin/make`` if you want more precision.
     If you don't want tox to issue a warning in any case, just use
@@ -136,7 +136,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
     using the ``{toxinidir}`` as the current working directory.
 
 .. confval:: setenv=MULTI-LINE-LIST
-   
+
    .. versionadded:: 0.9
 
    each line contains a NAME=VALUE environment variable setting which
@@ -164,17 +164,17 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     **DEPRECATED** -- as of August 2013 you should use setuptools
     which has merged most of distribute_ 's changes.  Just use
-    the default, Luke!  In future versions of tox this option might 
-    be ignored and setuptools always chosen.  
+    the default, Luke!  In future versions of tox this option might
+    be ignored and setuptools always chosen.
 
     **default:** False.
 
 .. confval:: sitepackages=True|False
 
     Set to ``True`` if you want to create virtual environments that also
-    have access to globally installed packages.  
+    have access to globally installed packages.
 
-    **default:** False, meaning that virtualenvs will be 
+    **default:** False, meaning that virtualenvs will be
     created without inheriting the global site packages.
 
 .. confval:: args_are_paths=BOOL
@@ -182,7 +182,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
     treat positional arguments passed to ``tox`` as file system paths
     and - if they exist on the filesystem - rewrite them according
     to the ``changedir``.
-    **default**: True (due to the exists-on-filesystem check it's 
+    **default**: True (due to the exists-on-filesystem check it's
     usually safe to try rewriting).
 
 .. confval:: envtmpdir=path
@@ -202,7 +202,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
    .. versionadded:: 0.9
 
    Multi-line ``name = URL`` definitions of python package servers.
-   Depedencies can specify using a specified index server through the
+   Dependencies can specify using a specified index server through the
    ``:indexservername:depname`` pattern.  The ``default`` indexserver
    definition determines where unscoped dependencies and the sdist install
    installs from.  Example::
@@ -347,7 +347,7 @@ You can put default values in one section and reference them in others to avoid
         pytest
         mock
         pytest-xdist
-    
+
     [testenv:dulwich]
     deps =
         dulwich
diff --git a/doc/example/devenv.txt b/doc/example/devenv.txt
index 571f89c..f4afc37 100644
--- a/doc/example/devenv.txt
+++ b/doc/example/devenv.txt
@@ -1,61 +1,78 @@
-
+=======================
 Development environment
 =======================
 
-Tox can be used to prepare development virtual environment for local projects.
-This feature can be useful in order to preserve environment across team members
-working on same project. It can be also used by deployment tools to prepare
-proper environments.
+Tox can be used for just preparing different virtual environments required by a
+project.
+
+This feature can be used by deployment tools when preparing deployed project
+environments. It can also be used for setting up normalized project development
+environments and thus help reduce the risk of different team members using
+mismatched development environments.
+
+Here are some examples illustrating how to set up a project's development
+environment using tox. For illustration purposes, let us call the development
+environment ``devenv``.
 
 
-Configuration
--------------
+Example 1: Basic scenario
+=========================
 
-Firstly, you need to prepare configuration for your development environment. In
-order to do that, we must define proper section at ``tox.ini`` file and tell at
-what directory environment should be created. Moreover, we need to specify
-python version that should be picked, and that the package should be installed
-with ``setup.py develop``::
+Step 1 - Configure the development environment
+----------------------------------------------
+
+First, we prepare the tox configuration for our development environment by
+defining a ``[testenv:devenv]`` section in the project's ``tox.ini``
+configuration file::
 
     [testenv:devenv]
     envdir = devenv
     basepython = python2.7
     usedevelop = True
-    commands =
-    deps =
 
+In it we state:
 
-Actually, you can configure a lot more, those are the only required settings.
-In example you can add ``deps`` and ``commands`` settings. Here, we tell tox
-not to pick ``commands`` or ``deps`` from base ``testenv`` configuration.
+- what directory to locate the environment in,
+- what Python executable to use in the environment,
+- that our project should be installed into the environment using ``setup.py
+  develop``, as opposed to building and installing its source distribution using
+  ``setup.py install``.
 
+Actually, we can configure a lot more, and these are only the required settings.
+For example, we can add the following to our configuration, telling tox not to
+reuse ``commands`` or ``deps`` settings from the base ``[testenv]``
+configuration::
+
+    commands =
+    deps =
 
-Creating development environment
---------------------------------
 
-Once ``devenv`` section is defined we can instrument tox to create our
-environment::
+Step 2 - Create the development environment
+-------------------------------------------
+
+Once the ``[testenv:devenv]`` configuration section has been defined, we create
+the actual development environment by running the following::
 
     tox -e devenv
 
-This will create an environment at path specified by ``envdir`` under
-``[testenv:devenv]`` section.
+This creates the environment at the path specified by the environment's
+``envdir`` configuration value.
+
 
+Example 2: A more complex scenario
+==================================
 
-Full configuration example
---------------------------
+Let us say we want our project development environment to:
 
-Let's say we want our development environment sit at ``devenv`` and pull
-packages from ``requirements.txt`` file which we create at the same directory
-as ``tox.ini`` file. We also want to speciy Python version to be 2.7, and use
-``setup.py develop`` to work in development mode instead of building and
-installing an ``sdist`` package.
+- be located in the ``devenv`` directory,
+- use Python executable ``python2.7``,
+- pull packages from ``requirements.txt``, located in the same directory as
+  ``tox.ini``.
 
-Here is example configuration for that::
+Here is an example configuration for the described scenario::
 
     [testenv:devenv]
     envdir = devenv
     basepython = python2.7
     usedevelop = True
     deps = -rrequirements.txt
-