revamp and document indexserver handling

2 files changed, 42 insertions, 27 deletions

diff --git a/doc/config.txt b/doc/config.txt
index 5354090..61e32c8 100644
--- a/doc/config.txt
+++ b/doc/config.txt
@@ -19,7 +19,7 @@ List of optional global options::
     distdir=path      # defaults to {toxworkdir}/dist
     distshare=path    # defaults to {homedir}/.tox/distshare
     envlist=ENVLIST   # defaults to the list of all environments
-    
+
 
 ``tox`` autodetects if it is running in a Hudson_ context
 (by checking for existence of the ``HUDSON_URL`` environment variable)
@@ -28,15 +28,7 @@ and will first lookup global tox settings in this section::
     [tox:hudson]
     ...               # override [tox] settings for the hudson context
     # note: for hudson distshare defaults to ``{toxworkdir}/distshare``.
-    
-.. confval:: indexserver=
-                name URL
-                name URL
-                ...
 
-    Definition of "name -> URL" mappings which can be used in
-    dependency specifications to install packages from different
-    indexservers.
 
 envlist setting
 +++++++++++++++++++++++++
@@ -48,6 +40,7 @@ happens in this order:
 * environment variable ``TOXENV``
 * ``tox.ini`` file's ``envlist``
 
+
 Virtualenv test environment settings
 -------------------------------------------
 
@@ -109,8 +102,14 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     dependencies to be installed into the environment prior to project
     package installation.  Each line defines a dependency, which will be
-    passed to easy_install/pip for processing.  It usually can be a file,
-    and URL or a package name.
+    passed to easy_install/pip for processing.  It can be a file,
+    and URL or a package name.  You can additionally specify
+    an :ref:`indexserver` to use for installing this dependency.
+    All derived dependencies (deps required by the dep) will be
+    loaded from the specified indexserver::
+
+        deps = :myindex:pkg
+
 
 .. confval:: recreate=True|False(default)
 
@@ -136,6 +135,22 @@ Complete list of settings that you can put into ``testenv*`` sections:
     have access to globally installed packages.  **default:** False, meaning
     that virtualenvs will be created with ``--no-site-packages`` by default.
 
+Index Server sections and settings
+-------------------------------------------
+
+Index servers can be specified by using the ``indexserver`` prefix
+in section names::
+
+    [indexserver:NAME]
+    url = XYZ
+
+Currently there is only one config option, ``url``, an URL
+to pass to ``pip_install`` or ``easy_install``.
+
+If you want to modify the default url definition you can use
+a ``[indexserver]`` definition.  This will be used for all
+unqualified dependency and sdist installations.
+
 Substitutions
 ---------------------
 
diff --git a/doc/example/basic.txt b/doc/example/basic.txt
index 8d1af3b..deeff98 100644
--- a/doc/example/basic.txt
+++ b/doc/example/basic.txt
@@ -45,18 +45,18 @@ see some of the examples in :doc:`examples <../examples>`.
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 
-using a different PyPI server
+using a different default PyPI url
 -----------------------------------------------
 
 .. versionadded: 0.9
 
 To install dependencies and packages from a different
-PyPI server type::
+default PyPI server type::
 
-    tox --indexserver http://pypi.testrun.org
+    tox -i http://pypi.testrun.org
 
-This causes both the internal pip and easy-install steps
-to use the specified server for upgrading.
+This causes tox to install dependencies and the sdist install step
+to use the specificied url as the index server.
 
 installing dependencies from multiple PyPI server
 ---------------------------------------------------
@@ -66,19 +66,19 @@ installing dependencies from multiple PyPI server
 You can instrument tox to install dependencies from
 different PyPI servers, example::
 
-    [tox]
-    indexserver =
-        DEV http://mypypiserver.org
+    [indexserver:DEV]
+    url = http://mypypiserver.org
 
     [testenv]
-    deps = 
-        docutils       # comes from standard PyPI
-        DEV mypackage  # will come from custom PYPI above
-
-Note that the ``--indexserver`` command line overrides 
-the default index server, not the ``DEV`` one here.
-This will cause both the internal pip and easy-install steps
-to use the specified servers accordingly.
+    deps =
+        docutils        # comes from standard PyPI
+        :DEV:mypackage  # will be installed from custom "DEV" pypi url
+
+Using the ``-i`` command line option you can override index urls::
+
+    tox -i DEV=http://pypi.python.org/simple  # changes :DEV: package URLs
+    tox -i http://pypi.python.org/simple      # changes default
+
 
 forcing re-creation of virtual environments
 -----------------------------------------------