From 4f91b3e2e5b767236b1967cddbb1df8091d93120 Mon Sep 17 00:00:00 2001 From: Alex Morega Date: Sun, 25 Sep 2011 07:51:49 +0300 Subject: [PATCH] improve installation documentation --- docs/usage.txt | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/docs/usage.txt b/docs/usage.txt index 22fc659a3..08f125cfd 100644 --- a/docs/usage.txt +++ b/docs/usage.txt @@ -9,13 +9,10 @@ Once you have pip, you can use it like this:: $ pip install SomePackage -SomePackage is some package you'll find on `PyPI +`SomePackage` is some package you'll find on `PyPI `_. This installs the package and all its dependencies. -pip does other stuff too, with packages, but install is the biggest -one. You can ``pip uninstall`` too. - You can also install from a URL (that points to a tar or zip file), install from some version control system (use URLs like ``hg+http://domain/repo`` -- or prefix ``git+``, ``svn+`` etc). pip @@ -23,15 +20,40 @@ knows a bunch of stuff about revisions and stuff, so if you need to do things like install a very specific revision from a repository pip can do that too. -If you've ever used ``python setup.py develop``, you can do something -like that with ``pip install -e ./`` -- this works with packages that -use ``distutils`` too (usually this only works with Setuptools -projects). - You can use ``pip install --upgrade SomePackage`` to upgrade to a newer version, or ``pip install SomePackage==1.0.4`` to install a very specific version. +Edit mode +********* + +Packages normally_ install under ``site-packages``, but when you're +making changes, it makes more sense to run the package straight from the +checked-out source tree. "Editable" installs create a ``.pth`` file in +``site-packages`` that extends Python's import path to find the +package:: + + $ pip install -e path/to/SomePackage + +.. _normally: http://docs.python.org/install/index.html#how-installation-works + +Version control systems +*********************** + +Pip knows how to check out a package from version control. The +repository will be checked out in a temporary folder, installed, and +cleaned up:: + + $ pip install git+https://github.com/simplejson/simplejson.git + $ pip install svn+svn://svn.zope.org/repos/main/zope.interface/trunk/ + +This can be combined with the `-e` flag, and Pip will perform the +checkout in ``./src/``. You need to supply a name for the checkout +folder by appending a hash to the repository URL:: + + $ pip install -e git+https://github.com/lakshmivyas/hyde.git#egg=hyde + + Uninstall packages ------------------