More docs for .py#egg and ``dependency_links``

--HG--
branch : setuptools
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/trunk/setuptools%4043429

2 files changed, 52 insertions, 0 deletions

diff --git a/EasyInstall.txt b/EasyInstall.txt
index ec10108c..b9795599 100755
--- a/EasyInstall.txt
+++ b/EasyInstall.txt
@@ -391,6 +391,19 @@ where you'd like the eggs placed.  By placing them in a directory that is
 published to the web, you can then make the eggs available for download, either
 in an intranet or to the internet at large.
 
+If someone distributes a package in the form of a single ``.py`` file, you can
+wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
+So, something like this::
+
+    easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+
+will install the package as an egg, and     
+
+    easy_install -zmaxd. \
+        -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+
+will create a ``.egg`` file in the current directory.
+
 
 Creating your own Package Index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/setuptools.txt b/setuptools.txt
index 1e93cd44..e93d9304 100755
--- a/setuptools.txt
+++ b/setuptools.txt
@@ -527,6 +527,45 @@ development work on it.  (See `"Development Mode"`_ below for more details on
 using ``setup.py develop``.)
 
 
+Dependencies that aren't in PyPI
+--------------------------------
+
+If your project depends on packages that aren't registered in PyPI, you may
+still be able to depend on them, as long as they are available for download
+as an egg, in the standard distutils ``sdist`` format, or as a single ``.py``
+file.  You just need to add some URLs to the ``dependency_links`` argument to
+``setup()``.
+
+The URLs must be either:
+
+1. direct download URLs, or
+2. the URLs of web pages that contain direct download links
+
+In general, it's better to link to web pages, because it is usually less
+complex to update a web page than to release a new version of your project.
+You can also use a SourceForge ``showfiles.php`` link in the case where a
+package you depend on is distributed via SourceForge.
+
+If you depend on a package that's distributed as a single ``.py`` file, you
+must include an ``#egg=project-version`` suffix to the URL, to give a project
+name and version number.  (Be sure to escape any dashes in the name or version
+by replacing them with underscores.)  EasyInstall will recognize this suffix
+and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file
+as an egg.
+
+The ``dependency_links`` option takes the form of a list of URL strings.  For
+example, the below will cause EasyInstall to search the specified page for
+eggs or source distributions, if the package's dependencies aren't already
+installed::
+
+    setup(
+        ...
+        dependency_links = [
+            "http://peak.telecommunity.com/snapshots/"
+        ],
+    )
+
+
 .. _Declaring Extras: