Merged upstream.

Author: miracle2k

announce.rst

@@ -1,5 +1,5 @@
 =======================
- virtualenvwrapper 2.8
+ virtualenvwrapper 2.9
 =======================
 
 What is virtualenvwrapper
@@ -11,14 +11,25 @@ virtual environments and otherwise managing your development workflow,
 making it easier to work on more than one project at a time without
 introducing conflicts in their dependencies.
 
-What's New in 2.8
+What's New in 2.9
 =================
 
-This release includes a fix to make ``cpvirtualenv`` use the copy of
-``virtualenv`` specified by the ``VIRTUALENVWRAPPER_VIRTUALENV``
-variable. It also adds support for running the wrapper commands under
-the MSYS environment on Microsoft Windows systems (contributed by
-noirbizarre).
+This release merges in the project directory management features
+previously delivered separately as ``virtualenvwrapper.project``.  The
+new command ``mkproject`` creates a working directory associated with
+a virtualenv, and can apply templates to populate the directory (for
+example, to create a new Django site).
+
+This release also adds a ``-r`` option to ``mkvirtualenv`` to specify
+a pip requirements file for packages that should be installed into the
+new environment after is is created.
+
+Upgrading to 2.9
+================
+
+Version 2.9 includes the features previously delivered separately by
+``virtualenvwrapper.project``.  If you have an older verison of the
+project extensions installed, remove them before upgrading.
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 

docs/en/command_ref.rst

@@ -22,10 +22,11 @@ Create a new environment, in the WORKON_HOME.
 
 Syntax::
 
-    mkvirtualenv [options] ENVNAME
+    mkvirtualenv [-r requirements_file] [virtualenv options] ENVNAME
 
-All command line options are passed directly to ``virtualenv``.  The
-new environment is automatically activated after being initialized.
+All command line options except ``-r`` and ``-h`` are passed directly
+to ``virtualenv``.  The new environment is automatically activated
+after being initialized.
 
 ::
 
@@ -40,10 +41,17 @@ new environment is automatically activated after being initialized.
     mynewenv
     (mynewenv)$ 
 
+The ``-r`` option can be used to specify a text file listing packages
+to be installed. The argument value is passed to ``pip -r`` to be
+installed.
+
 .. seealso::
 
    * :ref:`scripts-premkvirtualenv`
    * :ref:`scripts-postmkvirtualenv`
+   * `requirements file format`_
+
+.. _requirements file format: http://www.pip-installer.org/en/latest/requirement-format.html
 
 .. _command-lsvirtualenv:
 
@@ -394,3 +402,99 @@ output.
     Enabled global site-packages
     (env1)$ toggleglobalsitepackages -q
     (env1)$
+
+============================
+Project Directory Management
+============================
+
+.. seealso::
+
+   :ref:`project-management`
+
+.. _command-mkproject:
+
+mkproject
+---------
+
+Create a new virtualenv in the WORKON_HOME and project directory in
+PROJECT_HOME.
+
+Syntax::
+
+    mkproject [-t template] [virtualenv_options] ENVNAME
+
+The template option may be repeated to have several templates used to
+create a new project.  The templates are applied in the order named on
+the command line.  All other options are passed to ``mkvirtualenv`` to
+create a virtual environment with the same name as the project.
+
+::
+
+    $ mkproject myproj
+    New python executable in myproj/bin/python
+    Installing distribute.............................................
+    ..................................................................
+    ..................................................................
+    done.
+    Creating /Users/dhellmann/Devel/myproj
+    (myproj)$ pwd
+    /Users/dhellmann/Devel/myproj
+    (myproj)$ echo $VIRTUAL_ENV
+    /Users/dhellmann/Envs/myproj
+    (myproj)$ 
+
+.. seealso::
+
+  * :ref:`scripts-premkproject`
+  * :ref:`scripts-postmkproject`
+
+setvirtualenvproject
+--------------------
+
+Bind an existing virtualenv to an existing project.
+
+Syntax::
+
+  setvirtualenvproject [virtualenv_path project_path]
+
+The arguments to ``setvirtualenvproject`` are the full paths to the
+virtualenv and project directory.  An association is made so that when
+``workon`` activates the virtualenv the project is also activated.
+
+::
+
+    $ mkproject myproj
+    New python executable in myproj/bin/python
+    Installing distribute.............................................
+    ..................................................................
+    ..................................................................
+    done.
+    Creating /Users/dhellmann/Devel/myproj
+    (myproj)$ mkvirtualenv myproj_new_libs
+    New python executable in myproj/bin/python
+    Installing distribute.............................................
+    ..................................................................
+    ..................................................................
+    done.
+    Creating /Users/dhellmann/Devel/myproj
+    (myproj_new_libs)$ setvirtualenvproject $VIRTUAL_ENV $(pwd)
+
+When no arguments are given, the current virtualenv and current
+directory are assumed.
+
+Any number of virtualenvs can refer to the same project directory,
+making it easy to switch between versions of Python or other
+dependencies for testing.
+
+.. _command-cdproject:
+
+cdproject
+---------
+
+Change the current working directory to the one specified as the
+project directory for the active virtualenv.
+
+Syntax::
+
+  cdproject
+

docs/en/developers.rst

@@ -91,3 +91,30 @@ the ``tests`` directory.
 .. _shunit2: http://shunit2.googlecode.com/
 
 .. _tox: http://codespeak.net/tox
+
+.. _developer-templates:
+
+Creating a New Template
+=======================
+
+virtualenvwrapper.project templates work like `virtualenvwrapper
+plugins
+<http://www.doughellmann.com/docs/virtualenvwrapper/plugins.html>`__.
+The *entry point* group name is
+``virtualenvwrapper.project.template``.  Configure your entry point to
+refer to a function that will **run** (source hooks are not supported
+for templates).
+
+The argument to the template function is the name of the project being
+created.  The current working directory is the directory created to
+hold the project files (``$PROJECT_HOME/$envname``).
+
+Help Text
+---------
+
+One difference between project templates and other virtualenvwrapper
+extensions is that only the templates specified by the user are run.
+The ``mkproject`` command has a help option to give the user a list of
+the available templates.  The names are taken from the registered
+entry point names, and the descriptions are taken from the docstrings
+for the template functions.

docs/en/extensions.rst

@@ -5,25 +5,6 @@
 Below is a list of some of the extensions available for use with
 virtualenvwrapper.
 
-.. _extensions-user_scripts:
-
-project
-=======
-
-The project_ extension adds development directory management with
-templates to virtualenvwrapper.
-
-bitbucket
----------
-
-The bitbucket_ project template creates a working directory and
-automatically clones the repository from BitBucket.  Requires
-project_.
-
-.. _project: http://www.doughellmann.com/projects/virtualenvwrapper.project/
-
-.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
-
 emacs-desktop
 =============
 
@@ -37,6 +18,8 @@ one when activating a new virtualenv using ``workon``.
 
 .. _emacs-desktop: http://www.doughellmann.com/projects/virtualenvwrapper-emacs-desktop/
 
+.. _extensions-user_scripts:
+
 user_scripts
 ============
 
@@ -53,3 +36,34 @@ virtualenvwrapper, vim-virtualenv identifies the virtualenv to
 activate based on the name of the file being edited.
 
 .. _vim-virtualenv: https://github.com/jmcantrell/vim-virtualenv
+
+.. _extensions-templates:
+
+Templates
+=========
+
+Below is a list of some of the templates available for use with
+:ref:`command-mkproject`.
+
+.. _templates-bitbucket:
+
+bitbucket
+---------
+
+The bitbucket_ extension automatically clones a mercurial repository
+from the specified bitbucket project.
+
+.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
+
+.. _templates-django:
+
+django
+------
+
+The django_ extension automatically creates a new Django project.
+
+.. _django: http://www.doughellmann.com/projects/virtualenvwrapper.django/
+
+.. seealso::
+
+   * :ref:`developer-templates`

docs/en/history.rst

@@ -2,6 +2,17 @@
 Release History
 ===============
 
+2.9
+
+  - Change the shell function shell definition syntax so that ksh will
+    treat typeset-declared variables as local. No kidding.
+  - Merge the "project directory" features of the
+    ``virtualenvwrapper.project`` plugin into the main project, adding
+    :ref:`command-mkproject`, :ref:`command-cdproject`, and
+    :ref:`command-setvirtualenvproject` commands.
+  - Add ``-r`` option to :ref:`command-mkvirtualenv` to install
+    dependencies using a pip requirements file.
+
 2.8
 
   - Use VIRTUALENVWRAPPER_VIRTUALENV in `cpvirtualenv` (:bbissue:`104`).

docs/en/index.rst

@@ -175,6 +175,7 @@ Details
    install
    command_ref
    hooks
+   projects
    tips
    developers
    extensions

docs/en/install.rst

@@ -106,11 +106,13 @@ add it to `your user local directory
 Shell Startup File
 ==================
 
-Add two lines to your shell startup file (``.bashrc``, ``.profile``,
-etc.) to set the location where the virtual environments should live
-and the location of the script installed with this package::
+Add three lines to your shell startup file (``.bashrc``, ``.profile``,
+etc.) to set the location where the virtual environments should live,
+the location of your development project directorkes, and the location
+of the script installed with this package::
 
     export WORKON_HOME=$HOME/.virtualenvs
+    export PROJECT_HOME=$HOME/Devel
     source /usr/local/bin/virtualenvwrapper.sh
 
 After editing it, reload the startup file (e.g., run ``source
@@ -133,6 +135,8 @@ virtualenvwrapper can be customized by changing environment
 variables. Set the variables in your shell startup file *before*
 loading ``virtualenvwrapper.sh``.
 
+.. _variable-WORKON_HOME:
+
 Location of Environments
 ------------------------
 
@@ -141,6 +145,19 @@ your virtual environments.  The default is ``$HOME/.virtualenvs``. If
 the directory does not exist when virtualenvwrapper is loaded, it will
 be created automatically.
 
+.. _variable-PROJECT_HOME:
+
+Location of Project Directories
+-------------------------------
+
+The variable ``PROJECT_HOME`` tells virtualenvwrapper where to place
+your project working directories.  The variable must be set and the
+directory created before :ref:`command-mkproject` is used.
+
+.. seealso::
+
+   * :ref:`project-management`
+
 .. _variable-VIRTUALENVWRAPPER_HOOK_DIR:
 
 Location of Hook Scripts
@@ -150,6 +167,10 @@ The variable ``VIRTUALENVWRAPPER_HOOK_DIR`` tells virtualenvwrapper
 where the :ref:`user-defined hooks <scripts>` should be placed. The
 default is ``$WORKON_HOME``.
 
+.. seealso::
+
+   * :ref:`scripts`
+
 .. _variable-VIRTUALENVWRAPPER_LOG_DIR:
 
 Location of Hook Logs
@@ -231,6 +252,13 @@ users of that shell will have virtualenvwrapper enabled, and they
 cannot disable it. Refer to the documentation for the shell to
 identify the appropriate file to edit.
 
+Upgrading to 2.9
+================
+
+Version 2.9 includes the features previously delivered separately by
+``virtualenvwrapper.project``.  If you have an older verison of the
+project extensions installed, remove them before upgrading.
+
 Upgrading from 1.x
 ==================