merge virtualenvwrapper.project features into virtualenvwrapper

Author: dhellmann

docs/en/command_ref.rst

@@ -394,3 +394,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

@@ -6,6 +6,10 @@ dev
 
   - 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.
 
 2.8
 

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

docs/en/projects.rst

@@ -0,0 +1,36 @@
+.. _project-management:
+
+====================
+ Project Management
+====================
+
+A :term:`project directory` is associated with a virtualenv, but
+usually contains the source code under active development rather than
+the installed components needed to support the development. For
+example, the project directory may contain the source code checked out
+from a version control system, temporary artifacts created by testing,
+experimental files not committed to version control, etc.
+
+A project directory is created and bound to a virtualenv when
+:ref:`command-mkproject` is run instead of
+:ref:`command-mkvirtualenv`. To bind an existing project directory to
+a virtualenv, use :ref:`command-setvirtualenvproject`.
+
+Using Templates
+===============
+
+A new project directory can be created empty, or populated using one
+or more :term:`template` plugins. Templates should be specified as
+arguments to :ref:`command-mkproject`. Multiple values can be provided
+to apply more than one template. For example, to check out a Mercurial
+repository from on a project on bitbucket and create a new Django
+site, combine the :ref:`templates-bitbucket` and
+:ref:`templates-django` templates.
+
+::
+
+    $ mkproject -t bitbucket -t django my_site
+
+.. seealso::
+
+   * :ref:`extensions-templates`

docs/en/scripts.rst

@@ -203,3 +203,32 @@ postrmvirtualenv
 The ``$VIRTUALENVWRAPPER_HOOK_DIR/postrmvirtualenv`` script is run as an external
 program after the environment is removed. The full path to the
 environment directory is passed as an argument to the script.
+
+.. _scripts-premkproject:
+
+premkproject
+===============
+
+  :Global/Local: global
+  :Argument(s): name of new project
+  :Sourced/Run: run
+
+``$WORKON_HOME/premkproject`` is run as an external program after the
+virtual environment is created and after the current environment is
+switched to point to the new env, but before the new project directory
+is created. The current working directory for the script is
+``$PROJECT_HOME`` and the name of the new project is passed as an
+argument to the script.
+
+.. _scripts-postmkproject:
+
+postmkproject
+================
+
+  :Global/Local: global
+  :Argument(s): none
+  :Sourced/Run: sourced
+
+``$WORKON_HOME/postmkproject`` is sourced after the new environment
+and project directories are created and the virtualenv is activated.
+The current working directory is the project directory.

docs/sphinx/conf.py

@@ -47,7 +47,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.8'
+version = '2.9'
 # The full version, including alpha/beta/rc tags.
 release = version