Expand 'alternate package repositories' documentation to be more accurate and include mention of --find-links. Fixes #388 - thanks Lorin Hochstein for the report.

1 files changed, 35 insertions, 7 deletions

diff --git a/docs/usage.txt b/docs/usage.txt
index a0421fcee..24582dd57 100644
--- a/docs/usage.txt
+++ b/docs/usage.txt
@@ -54,19 +54,47 @@ folder by appending a hash to the repository URL::
 Alternate package repositories
 ******************************
 
-pip searches in :term:`PyPI` by default, but this can be overridden,
-using the ``--index-url`` option::
+pip searches in :term:`PyPI` by default, but this can be overridden using the
+``--index-url`` option::
 
     $ pip install --index-url http://d.pypi.python.org/simple/ SomePackage
 
-If some package is not in PyPI, but in a private repository, it makes
-sense to specify additional search URLs (see `Your own python egg
-baskets / package repositories`_ for a guide on creating simple
-repositories)::
+If you have your own package index with a few additional packages, you may want
+to to specify additional index URLs while still also using :term:`PyPI`::
 
     $ pip install --extra-index-url http://my.package.repo/ SomePackage
 
-.. _`Your own python egg baskets / package repositories`: http://labs.creativecommons.org/2011/02/14/your-own-python-egg-baskets-package-repositories/
+A "package index" used with ``--index-url`` or ``--extra-index-url`` can be as
+simple as a static-web-served directory, with automatic indexes on, with a
+subdirectory per package and sdists (tarballs created with ``python setup.py
+sdist``) in that directory::
+
+    mypackage/
+        mypackage-0.7.8.tar.gz
+        mypackage-1.0.1.tar.gz
+    otherpackage/
+        otherpackage-2.3.5.tar.gz
+
+If the number of packages in the index is small, it's even simpler to skip the
+subdirectories: put all of the sdists in a single directory and use pip's
+``--find-links`` option with a URL to that directory::
+
+    mypackage-0.7.8.tar.gz
+    mypackage-1.0.1.tar.gz
+    otherpackage-2.3.5.tar.gz
+
+``--find-links`` also supports local paths, so installation need not require a
+network connection.
+
+Like ``--extra-index-url``, ``--find-links`` is additive by default, it does
+not replace or supersede the index. All package sources are checked, and the
+latest qualifying version for every requested package is used. If you want only
+your ``-find-links`` URL used as package source, you need to pair it with
+``--no-index``.
+
+``--index-url``, ``--extra-index-url`` and ``--find-links`` can all be used
+within a :ref:`requirements file <requirements-files>` in addition to on the
+command line directly.
 
 
 Uninstall packages