Skip to content

Commit 3c306e1

Browse files
dhellmanndhellmann
committed
merge virtualenvwrapper.project features into virtualenvwrapper
1 parent e051200 commit 3c306e1

17 files changed

+771
-24
lines changed

‎docs/en/command_ref.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,3 +394,99 @@ output.
394394
Enabled global site-packages
395395
(env1)$ toggleglobalsitepackages -q
396396
(env1)$
397+
398+
============================
399+
Project Directory Management
400+
============================
401+
402+
.. seealso::
403+
404+
:ref:`project-management`
405+
406+
.. _command-mkproject:
407+
408+
mkproject
409+
---------
410+
411+
Create a new virtualenv in the WORKON_HOME and project directory in
412+
PROJECT_HOME.
413+
414+
Syntax::
415+
416+
mkproject [-t template] [virtualenv_options] ENVNAME
417+
418+
The template option may be repeated to have several templates used to
419+
create a new project. The templates are applied in the order named on
420+
the command line. All other options are passed to ``mkvirtualenv`` to
421+
create a virtual environment with the same name as the project.
422+
423+
::
424+
425+
$ mkproject myproj
426+
New python executable in myproj/bin/python
427+
Installing distribute.............................................
428+
..................................................................
429+
..................................................................
430+
done.
431+
Creating /Users/dhellmann/Devel/myproj
432+
(myproj)$ pwd
433+
/Users/dhellmann/Devel/myproj
434+
(myproj)$ echo $VIRTUAL_ENV
435+
/Users/dhellmann/Envs/myproj
436+
(myproj)$
437+
438+
.. seealso::
439+
440+
* :ref:`scripts-premkproject`
441+
* :ref:`scripts-postmkproject`
442+
443+
setvirtualenvproject
444+
--------------------
445+
446+
Bind an existing virtualenv to an existing project.
447+
448+
Syntax::
449+
450+
setvirtualenvproject [virtualenv_path project_path]
451+
452+
The arguments to ``setvirtualenvproject`` are the full paths to the
453+
virtualenv and project directory. An association is made so that when
454+
``workon`` activates the virtualenv the project is also activated.
455+
456+
::
457+
458+
$ mkproject myproj
459+
New python executable in myproj/bin/python
460+
Installing distribute.............................................
461+
..................................................................
462+
..................................................................
463+
done.
464+
Creating /Users/dhellmann/Devel/myproj
465+
(myproj)$ mkvirtualenv myproj_new_libs
466+
New python executable in myproj/bin/python
467+
Installing distribute.............................................
468+
..................................................................
469+
..................................................................
470+
done.
471+
Creating /Users/dhellmann/Devel/myproj
472+
(myproj_new_libs)$ setvirtualenvproject $VIRTUAL_ENV $(pwd)
473+
474+
When no arguments are given, the current virtualenv and current
475+
directory are assumed.
476+
477+
Any number of virtualenvs can refer to the same project directory,
478+
making it easy to switch between versions of Python or other
479+
dependencies for testing.
480+
481+
.. _command-cdproject:
482+
483+
cdproject
484+
---------
485+
486+
Change the current working directory to the one specified as the
487+
project directory for the active virtualenv.
488+
489+
Syntax::
490+
491+
cdproject
492+

‎docs/en/developers.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,30 @@ the ``tests`` directory.
9191
.. _shunit2: http://shunit2.googlecode.com/
9292

9393
.. _tox: http://codespeak.net/tox
94+
95+
.. _developer-templates:
96+
97+
Creating a New Template
98+
=======================
99+
100+
virtualenvwrapper.project templates work like `virtualenvwrapper
101+
plugins
102+
<http://www.doughellmann.com/docs/virtualenvwrapper/plugins.html>`__.
103+
The *entry point* group name is
104+
``virtualenvwrapper.project.template``. Configure your entry point to
105+
refer to a function that will **run** (source hooks are not supported
106+
for templates).
107+
108+
The argument to the template function is the name of the project being
109+
created. The current working directory is the directory created to
110+
hold the project files (``$PROJECT_HOME/$envname``).
111+
112+
Help Text
113+
---------
114+
115+
One difference between project templates and other virtualenvwrapper
116+
extensions is that only the templates specified by the user are run.
117+
The ``mkproject`` command has a help option to give the user a list of
118+
the available templates. The names are taken from the registered
119+
entry point names, and the descriptions are taken from the docstrings
120+
for the template functions.

‎docs/en/extensions.rst‎

Lines changed: 33 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,6 @@
55
Below is a list of some of the extensions available for use with
66
virtualenvwrapper.
77

8-
.. _extensions-user_scripts:
9-
10-
project
11-
=======
12-
13-
The project_ extension adds development directory management with
14-
templates to virtualenvwrapper.
15-
16-
bitbucket
17-
---------
18-
19-
The bitbucket_ project template creates a working directory and
20-
automatically clones the repository from BitBucket. Requires
21-
project_.
22-
23-
.. _project: http://www.doughellmann.com/projects/virtualenvwrapper.project/
24-
25-
.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
26-
278
emacs-desktop
289
=============
2910

@@ -37,6 +18,8 @@ one when activating a new virtualenv using ``workon``.
3718

3819
.. _emacs-desktop: http://www.doughellmann.com/projects/virtualenvwrapper-emacs-desktop/
3920

21+
.. _extensions-user_scripts:
22+
4023
user_scripts
4124
============
4225

@@ -53,3 +36,34 @@ virtualenvwrapper, vim-virtualenv identifies the virtualenv to
5336
activate based on the name of the file being edited.
5437

5538
.. _vim-virtualenv: https://github.com/jmcantrell/vim-virtualenv
39+
40+
.. _extensions-templates:
41+
42+
Templates
43+
=========
44+
45+
Below is a list of some of the templates available for use with
46+
:ref:`command-mkproject`.
47+
48+
.. _templates-bitbucket:
49+
50+
bitbucket
51+
---------
52+
53+
The bitbucket_ extension automatically clones a mercurial repository
54+
from the specified bitbucket project.
55+
56+
.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
57+
58+
.. _templates-django:
59+
60+
django
61+
------
62+
63+
The django_ extension automatically creates a new Django project.
64+
65+
.. _django: http://www.doughellmann.com/projects/virtualenvwrapper.django/
66+
67+
.. seealso::
68+
69+
* :ref:`developer-templates`

‎docs/en/history.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ dev
66

77
- Change the shell function shell definition syntax so that ksh will
88
treat typeset-declared variables as local. No kidding.
9+
- Merge the "project directory" features of the
10+
``virtualenvwrapper.project`` plugin into the main project, adding
11+
:ref:`command-mkproject`, :ref:`command-cdproject`, and
12+
:ref:`command-setvirtualenvproject` commands.
913

1014
2.8
1115

‎docs/en/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,7 @@ Details
175175
install
176176
command_ref
177177
hooks
178+
projects
178179
tips
179180
developers
180181
extensions

‎docs/en/install.rst‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -106,11 +106,13 @@ add it to `your user local directory
106106
Shell Startup File
107107
==================
108108

109-
Add two lines to your shell startup file (``.bashrc``, ``.profile``,
110-
etc.) to set the location where the virtual environments should live
111-
and the location of the script installed with this package::
109+
Add three lines to your shell startup file (``.bashrc``, ``.profile``,
110+
etc.) to set the location where the virtual environments should live,
111+
the location of your development project directorkes, and the location
112+
of the script installed with this package::
112113

113114
export WORKON_HOME=$HOME/.virtualenvs
115+
export PROJECT_HOME=$HOME/Devel
114116
source /usr/local/bin/virtualenvwrapper.sh
115117

116118
After editing it, reload the startup file (e.g., run ``source
@@ -133,6 +135,8 @@ virtualenvwrapper can be customized by changing environment
133135
variables. Set the variables in your shell startup file *before*
134136
loading ``virtualenvwrapper.sh``.
135137

138+
.. _variable-WORKON_HOME:
139+
136140
Location of Environments
137141
------------------------
138142

@@ -141,6 +145,19 @@ your virtual environments. The default is ``$HOME/.virtualenvs``. If
141145
the directory does not exist when virtualenvwrapper is loaded, it will
142146
be created automatically.
143147

148+
.. _variable-PROJECT_HOME:
149+
150+
Location of Project Directories
151+
-------------------------------
152+
153+
The variable ``PROJECT_HOME`` tells virtualenvwrapper where to place
154+
your project working directories. The variable must be set and the
155+
directory created before :ref:`command-mkproject` is used.
156+
157+
.. seealso::
158+
159+
* :ref:`project-management`
160+
144161
.. _variable-VIRTUALENVWRAPPER_HOOK_DIR:
145162

146163
Location of Hook Scripts
@@ -150,6 +167,10 @@ The variable ``VIRTUALENVWRAPPER_HOOK_DIR`` tells virtualenvwrapper
150167
where the :ref:`user-defined hooks <scripts>` should be placed. The
151168
default is ``$WORKON_HOME``.
152169

170+
.. seealso::
171+
172+
* :ref:`scripts`
173+
153174
.. _variable-VIRTUALENVWRAPPER_LOG_DIR:
154175

155176
Location of Hook Logs

‎docs/en/projects.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. _project-management:
2+
3+
====================
4+
Project Management
5+
====================
6+
7+
A :term:`project directory` is associated with a virtualenv, but
8+
usually contains the source code under active development rather than
9+
the installed components needed to support the development. For
10+
example, the project directory may contain the source code checked out
11+
from a version control system, temporary artifacts created by testing,
12+
experimental files not committed to version control, etc.
13+
14+
A project directory is created and bound to a virtualenv when
15+
:ref:`command-mkproject` is run instead of
16+
:ref:`command-mkvirtualenv`. To bind an existing project directory to
17+
a virtualenv, use :ref:`command-setvirtualenvproject`.
18+
19+
Using Templates
20+
===============
21+
22+
A new project directory can be created empty, or populated using one
23+
or more :term:`template` plugins. Templates should be specified as
24+
arguments to :ref:`command-mkproject`. Multiple values can be provided
25+
to apply more than one template. For example, to check out a Mercurial
26+
repository from on a project on bitbucket and create a new Django
27+
site, combine the :ref:`templates-bitbucket` and
28+
:ref:`templates-django` templates.
29+
30+
::
31+
32+
$ mkproject -t bitbucket -t django my_site
33+
34+
.. seealso::
35+
36+
* :ref:`extensions-templates`

‎docs/en/scripts.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,3 +203,32 @@ postrmvirtualenv
203203
The ``$VIRTUALENVWRAPPER_HOOK_DIR/postrmvirtualenv`` script is run as an external
204204
program after the environment is removed. The full path to the
205205
environment directory is passed as an argument to the script.
206+
207+
.. _scripts-premkproject:
208+
209+
premkproject
210+
===============
211+
212+
:Global/Local: global
213+
:Argument(s): name of new project
214+
:Sourced/Run: run
215+
216+
``$WORKON_HOME/premkproject`` is run as an external program after the
217+
virtual environment is created and after the current environment is
218+
switched to point to the new env, but before the new project directory
219+
is created. The current working directory for the script is
220+
``$PROJECT_HOME`` and the name of the new project is passed as an
221+
argument to the script.
222+
223+
.. _scripts-postmkproject:
224+
225+
postmkproject
226+
================
227+
228+
:Global/Local: global
229+
:Argument(s): none
230+
:Sourced/Run: sourced
231+
232+
``$WORKON_HOME/postmkproject`` is sourced after the new environment
233+
and project directories are created and the virtualenv is activated.
234+
The current working directory is the project directory.

‎docs/sphinx/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
# built documents.
4848
#
4949
# The short X.Y version.
50-
version = '2.8'
50+
version = '2.9'
5151
# The full version, including alpha/beta/rc tags.
5252
release = version
5353

0 commit comments

Comments
 (0)