Browse files

Expand "usage" documentation; create glossary

  • Loading branch information...
1 parent 951f6a7 commit 4cdaccf11ded71f53e5e80259a8d0751c01b7d05 @mgax mgax committed Oct 15, 2011
Showing with 49 additions and 23 deletions.
  1. +12 −0 docs/glossary.txt
  2. +1 −0 docs/index.txt
  3. +36 −23 docs/usage.txt
@@ -0,0 +1,12 @@
+.. glossary::
+ PyPI
+ The `Python Package Index`_, formerly known as the Cheese Shop,
+ is a central catalog of Python packages. By default, when
+ installing packages,`pip` searches for them in PyPI.
+ .. _`Python Package Index`:
@@ -40,6 +40,7 @@ Removing a package::
+ glossary
.. comment: split here
@@ -5,24 +5,22 @@ Usage
Install packages
-Once you have pip, you can use it like this::
+The simplest way to install a package is by specifying its name::
$ pip install SomePackage
-`SomePackage` is some package you'll find on `PyPI
-<>`_. This installs the package and all
-its dependencies.
+`SomePackage` is downloaded from :term:`PyPI`, along with its
+dependencies, and installed.
-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
-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 `SomePackage` is already installed, and you need a newer version, use
+``pip install --upgrade SomePackage``. You can also request a specific
+version: ``pip install SomePackage==1.0.4``.
-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.
+You can also install from a particular source distribution file, either
+local or remote::
+ $ pip install ./downloads/SomePackage-1.0.4.tar.gz
+ $ pip install http://my.package.repo/
Edit mode
@@ -40,9 +38,9 @@ package::
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 knows how to check out a package from version control. `Subversion`,
+`Git`, `Mercurial` and `Bazaar` are supported. The repository will be
+checked out in a temporary folder, installed, and cleaned up::
$ pip install git+
$ pip install svn+svn://
@@ -53,6 +51,23 @@ folder by appending a hash to the repository URL::
$ pip install -e git+
+Alternate package repositories
+pip searches in :term:`PyPI` by default, but this can be overridden,
+using the ``--index-url`` option::
+ $ pip install --index-url 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
+ $ pip install --extra-index-url http://my.package.repo/ SomePackage
+.. _`Your own python egg baskets / package repositories`:
Uninstall packages
@@ -74,16 +89,14 @@ fails to download or install.
Searching for packages
-pip can search the `Python Package Index <>`_ (PyPI)
-for packages using the ``pip search`` command. To search, run::
+pip can search :term:`PyPI` for packages using the ``pip search``
$ pip search "query"
-The query will be used to search the names and summaries of all packages
-pip searches by default but alternative indexes
-can be searched by using the ``--index`` flag.
+The query will be used to search the names and summaries of all
+packages. With the ``--index`` option you can search in a different

0 comments on commit 4cdaccf

Please sign in to comment.