Changed packaging format to something less troublesome, and added docs for it.

docs/gettingstarted.rst

@@ -6,7 +6,7 @@ Requirements
 
 You need Python 2.6.
 
-To check out playdoh, run:
+To check out playdoh, run::
 
     git clone --recursive git://github.com/mozilla/playdoh.git
 
@@ -18,15 +18,14 @@ In addition, there are compiled libraries (such as Jinja2) that you will need
 to build yourself, either by installing them from ``pypi`` or by using your
 favorite package manager for your OS.
 
-For development, you can run this in a `virtualenv environment`_:
+For development, you can run this in a `virtualenv environment`_::
 
     easy_install pip
     pip install -r requirements/compiled.txt
 
-For more information on vendor libraries, read `Packaging in Zamboni`_.
+For more information on vendor libraries, read :ref:`packages`.
 
 .. _virtualenv environment: http://pypi.python.org/pypi/virtualenv
-.. _packaging in Zamboni: http://jbalogh.github.com/zamboni/topics/packages/
 
 
 Starting a project based on playdoh

docs/index.rst

@@ -37,13 +37,14 @@ Contents
    :maxdepth: 1
 
    gettingstarted
+   libs
    operations
    migrations
-   bestpractices
    l10n_setup
    l10n_update
-   libs
+   packages
    docs
+   bestpractices
 
 
 Indices and tables

docs/packages.rst

@@ -0,0 +1,104 @@
+.. _packages:
+
+==========================
+pip and friends: Packaging
+==========================
+
+*(largely borrowed from Zamboni)*
+
+There are two ways of getting packages in your playdoh-based project. The
+first is to install everything using pip. We have our packages separated into
+three files:
+
+:src:`requirements/compiled.txt`
+    All packages that require (or go faster with) compilation.  These can't be
+    distributed cross-platform, so they need to be installed through your
+    system's package manager or pip.
+
+:src:`requirements/prod.txt`
+    The minimal set of packages you need to run zamboni in production.  You
+    also need to get ``requirements/compiled.txt``.
+
+:src:`requirements/dev.txt`
+    All the packages needed for running tests and development servers.  This
+    automatically includes ``requirements/prod.txt``.
+
+
+Installing through pip
+----------------------
+
+You can get a development environment with ::
+
+    pip install -r requirements/dev.txt -r requirements/compiled.txt
+
+
+Using the vendor library
+------------------------
+
+The other method is to use the /vendor library of all packages and
+repositories.
+
+By default, the vendor lib is checked out as a *git submodule* under
+``vendor/``. If you *do* need to check it out separately, do::
+
+    git clone --recursive git://github.com/mozilla/playdoh-lib.git ./vendor
+
+Once the playdoh-lib repo has been downloaded to ``/vendor``, you only need to
+install the compiled packages.  These can come from your system package manager
+or from ::
+
+    pip install -r requirements/compiled.txt
+
+
+Adding new packages
+-------------------
+
+The vendor repo was seeded with ::
+
+    pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' -r requirements/dev.txt
+
+    # ..delete some junk from vendor/lib/python...
+
+    # Create the .pth file so Python can find our src libs.
+    find src -type d -depth 1 >> zamboni.pth
+
+    # Add all the submodules.
+    for f in src/*; do
+        pushd $f >/dev/null && REPO=$(git config remote.origin.url) && popd > /dev/null && git submodule add $REPO $f
+    done
+    git add .
+
+
+If we wanted to add a new dependency called ``cheeseballs`` to zamboni, you
+would add it to ``requirements/prod.txt`` or ``requirements/dev.txt`` and then
+do::
+
+    pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' cheeseballs
+
+or for a git-based package::
+
+    pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' -e git://github.com/mozilla/something.git#egg=something
+
+For git-based packages, you then need to update ``vendor/vendor.pth``. Python
+uses ``.pth`` files to dynamically add directories to ``sys.path`` (`docs
+<http://docs.python.org/library/site.html>`_).
+
+I created ``vendor.pth`` with this::
+
+    find src/ -type d -depth 1 > vendor.pth
+
+Some packages (like ``html5lib`` and ``selenium``) are troublesome, because
+their source lives inside an extra subdirectory ``src/`` inside their checkout.
+So they need to be sourced with ``src/html5lib/src``, for example. Hopefully
+you won't hit any snags like that.
+
+
+Adding submodules
+~~~~~~~~~~~~~~~~~
+
+You want to make your git-based packages *git submodules* inside the vendor
+library. To set up the first batch of submodules, something like the following
+happened::
+
+    for f in src/*
+        pushd $f && REPO=$(git config remote.origin.url) && popd && git submodule add $REPO $f

vendor

@@ -1 +1 @@
-Subproject commit f3469bc56d62592e37fbe280805674d01e010d98
+Subproject commit 214e3840828a67ed96338cefc596a98b630d7fa9