Skip to content

Commit 8dfb27d

Browse files
dhellmanndhellmann
committed
clean up and update docs, reduce size of readme, start working on packaging changes
1 parent c394718 commit 8dfb27d

File tree

8 files changed

+265
-350
lines changed

8 files changed

+265
-350
lines changed

‎MANIFEST.in

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@ include paver-minilib.zip
44
include pavement.py
55
include tests/*
66
recursive-include docs *.html *.txt *.css *.js *.png
7-
recursive-include docsource *.rst *.txt *.py
7+
recursive-include docsource *.rst

‎README

Lines changed: 2 additions & 195 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
virtualenvwrapper
33
#################
44

5+
virtualenvwrapper is a set of extensions to Ian Bicking's `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ tool. The extensions include wrappers for creating and deleting 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.
6+
57
===========
68
Quick Setup
79
===========
@@ -19,128 +21,6 @@ Quick Setup
1921
7. Run: ``workon``
2022
8. This time, the ``temp`` environment is included.
2123

22-
23-
===============
24-
Path Management
25-
===============
26-
27-
Sometimes it is desirable to share installed packages that are not in the system ``site-pacakges`` directory and which you do not want to install in each virtualenv. In this case, you *could* symlink the source into the environment ``site-packages`` directory, but it is also easy to add extra directories to the PYTHONPATH by including them in a .pth file inside ``site-packages`` using ``add2virtualenv``.
28-
29-
1. Check out the source for a big project, such as Django.
30-
2. Run: ``add2virtualenv path_to_source``.
31-
3. Run: ``add2virtualenv``.
32-
4. A usage message and list of current "extra" paths is printed.
33-
34-
============
35-
Hook Scripts
36-
============
37-
38-
virtualenvwrapper adds several hook points you can use to change your settings when creating,
39-
deleting, or moving between environments. They are either *sourced* (allowing them to modify
40-
your shell environment) or run as an external program at the appropriate trigger time.
41-
42-
$VIRTUAL_ENV/bin/postactivate
43-
=============================
44-
45-
The ``postactivate`` script is sourced after the new environment is enabled. ``$VIRTUAL_ENV``
46-
refers to the new environment at the time the script runs.
47-
48-
This example script for the PyMOTW environment changes the current working directory and the
49-
PATH variable to refer to the source tree containing the PyMOTW source.
50-
51-
::
52-
53-
pymotw_root=/Users/dhellmann/Documents/PyMOTW
54-
cd $pymotw_root
55-
PATH=$pymotw_root/bin:$PATH
56-
57-
$VIRTUAL_ENV/bin/predeactivate
58-
==============================
59-
60-
The ``predeactivate`` script is source before the current environment is deactivated, and can
61-
be used to disable or clear settings in your environment. ``$VIRTUAL_ENV`` refers to the old
62-
environment at the time the script runs.
63-
64-
$WORKON_HOME/postactivate
65-
=============================
66-
67-
The global ``postactivate`` script is sourced after the new environment is enabled and the new
68-
environment's postactivate is sourced (if it exists). ``$VIRTUAL_ENV`` refers to the new
69-
environment at the time the script runs.
70-
71-
This example script adds a space between the virtual environment name and your old PS1 by making
72-
use of ``_OLD_VIRTUAL_PS1``.
73-
74-
::
75-
76-
PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"
77-
78-
$WORKON_HOME/premkvirtualenv
79-
=============================
80-
81-
The ``premkvirtualenv`` script is run as an external program after the virtual environment is
82-
created but before the current environment is switched to point to the new env. The current
83-
working directory for the script is ``$WORKON_HOME`` and the name of the new environment is
84-
passed as an argument to the script.
85-
86-
$WORKON_HOME/postmkvirtualenv
87-
=============================
88-
89-
The ``postmkvirtualenv`` script is sourced after the new environment is created and
90-
activated.
91-
92-
$WORKON_HOME/prermvirtualenv
93-
============================
94-
95-
The ``prermvirtualenv`` script is run as an external program before the environment is
96-
removed. The full path to the environment directory is passed as an argument to the script.
97-
98-
$WORKON_HOME/postrmvirtualenv
99-
=============================
100-
101-
The ``postrmvirtualenv`` script is run as an external program after the environment is
102-
removed. The full path to the environment directory is passed as an argument to the script.
103-
104-
===============
105-
Path Management
106-
===============
107-
108-
The function ``add2virtualenv`` adds the specified directories to the Python path for the
109-
active virtualenv. The directory names passed as argument are added to a path file named
110-
``virtualenv_path_extensions.pth`` inside the virtualenv's site-packages directory. If this
111-
file does not exist, it will be created first.
112-
113-
==================================
114-
Quickly Navigating to a virtualenv
115-
==================================
116-
117-
There are two functions to provide shortcuts to navigate into the the currently-active
118-
virtualenv.
119-
120-
cdvirtualenv
121-
============
122-
123-
Calling ``cdvirtualenv`` changes the current working directory to the top of the virtualenv (``$VIRTUAL_ENV``). An optional argument is appended to the path, allowing navigation directly into a subdirectory.
124-
125-
::
126-
127-
$ workon pymotw
128-
$ echo $VIRTUAL_ENV
129-
/Users/dhellmann/.virtualenvs/pymotw
130-
$ cdvirtualenv
131-
$ pwd
132-
/Users/dhellmann/.virtualenvs/pymotw
133-
$ cdvirtualenv bin
134-
$ pwd
135-
/Users/dhellmann/.virtualenvs/pymotw/bin
136-
137-
cdsitepackages
138-
==============
139-
140-
Because the exact path to the site-packages directory in the virtualenv depends on the
141-
version of Python, ``cdsitepackages`` is provided as a shortcut for ``cdvirtualenv
142-
lib/python${pyvers}/site-packages``.
143-
14424
==========
14525
References
14626
==========
@@ -149,79 +29,6 @@ For more details, refer to the column published in the May 2008 issue of Python
14929
`virtualenvwrapper | And Now For Something Completely Different
15030
<http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html>`_.
15131

152-
=======
153-
Updates
154-
=======
155-
156-
1.16
157-
158-
- Merged in changes to ``cdvirtualenv`` from wam and added tests and docs.
159-
- Merged in changes to make error messages go to stderr, also provided by wam.
160-
161-
1.15
162-
- Better error handling in mkvirtualenv.
163-
- Remove bogus VIRTUALENV_WRAPPER_BIN variable.
164-
165-
1.14
166-
- Wrap the virtualenv version of deactivate() with one that lets us invoke
167-
the predeactivate hooks.
168-
- Fix virtualenvwrapper_show_workon_options for colorized versions of ls and
169-
write myself a note so I don't break it again later.
170-
- Convert test.sh to use true tests with `shunit2 <http://shunit2.googlecode.com/>`_
171-
172-
1.13
173-
- Fix issue #5 by correctly handling symlinks and limiting the list of envs to things
174-
that look like they can be activated.
175-
176-
1.12
177-
- Check return value of virtualenvwrapper_verify_workon_home everywhere, thanks to
178-
Jeff Forcier for pointing out the errors.
179-
- Fix instructions at top of README, pointed out by Matthew Scott.
180-
- Add cdvirtualenv and cdsitepackages, contributed by James Bennett.
181-
- Enhance test.sh.
182-
183-
1.11
184-
- Optimize virtualenvwrapper_show_workon_options.
185-
- Add global postactivate hook.
186-
187-
1.10
188-
- Pull in fix for colorized ls from Jeff Forcier (b42a25f7b74a).
189-
190-
1.9
191-
- Add more hooks for operations to run before and after creating or deleting environments based on changes from Chris Hasenpflug.
192-
193-
1.8.1
194-
- Corrected a problem with change to mkvirtualenv that lead to release 1.8 by using an alternate fix proposed by James in comments on release 1.4.
195-
196-
1.8
197-
- Fix for processing the argument list in mkvirtualenv from jorgevargas (BitBucket issue #1)
198-
199-
1.7
200-
- Move to bitbucket.org for hosting
201-
- clean up TODO list and svn keywords
202-
- add license section below
203-
204-
1.6.1
205-
206-
- More zsh support (fixes to rmvirtualenv) from Byron Clark.
207-
208-
1.6
209-
210-
- Add completion support for zsh, courtesy of Ted Leung.
211-
212-
1.5
213-
214-
- Fix some issues with spaces in directory or env names. They still don't really work with virtualenv, though.
215-
- Added documentation for the postactivate and predeactivate scripts.
216-
217-
1.4
218-
219-
- Includes a new .pth management function based on work contributed by James Bennett and Jannis Leidel.
220-
221-
1.3.x
222-
223-
- Includes a fix for a nasty bug in rmvirtualenv identified by John Shimek.
224-
22532
=======
22633
License
22734
=======

‎docsource/command_ref.rst

Lines changed: 81 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,102 @@
11
.. Quick reference documentation for virtualenvwrapper command line functions
2-
Created Thursday, May 28, 2009 by Steve Steiner ([email protected])
2+
Originally contributed Thursday, May 28, 2009 by Steve Steiner ([email protected])
33
4-
==================
4+
#################
55
Command Reference
6-
==================
6+
#################
77

88
All of the commands below are to be used on the Terminal command line.
99

10-
add2virtualenv
11-
--------------
12-
13-
add2virtualenv directory1 directory2 ...
14-
15-
Path management for packages outside of the virtual env.
16-
Based on a contribution from James Bennett and Jannis Leidel.
17-
18-
19-
Adds the specified directories to the Python path for the currently-active
20-
virtualenv.
21-
22-
This will be done by placing the directory names in a path file
23-
named "virtualenv_path_extensions.pth" inside the virtualenv's site-packages
24-
directory; if this file does not exist, it will be created first.
10+
=====================
11+
Managing Environments
12+
=====================
2513

2614
mkvirtualenv
2715
------------
2816

2917
Create a new environment, in the WORKON_HOME.
3018

31-
Usage: mkvirtualenv [options] ENVNAME
19+
Syntax::
20+
21+
mkvirtualenv [options] ENVNAME
3222

3323
(where the options are passed directly to virtualenv)
3424

3525
rmvirtualenv
3626
------------
27+
3728
Remove an environment, in the WORKON_HOME.
3829

39-
Usage: rmvirtualenv ENVNAME
30+
Syntax::
31+
32+
rmvirtualenv ENVNAME
4033

4134
workon
42-
# List or change working virtual environments
43-
#
44-
# Usage: workon [environment_name]
45-
#
35+
------
36+
37+
List or change working virtual environments
38+
39+
Syntax::
40+
41+
workon [environment_name]
42+
43+
If no ``environment_name`` is given the list of available environments is printed to stdout.
44+
45+
==================================
46+
Quickly Navigating to a virtualenv
47+
==================================
48+
49+
There are two functions to provide shortcuts to navigate into the the currently-active
50+
virtualenv.
51+
52+
cdvirtualenv
53+
------------
54+
55+
Calling ``cdvirtualenv`` changes the current working directory to the top of the virtualenv (``$VIRTUAL_ENV``). An optional argument is appended to the path, allowing navigation directly into a subdirectory.
56+
57+
::
58+
59+
$ workon pymotw
60+
$ echo $VIRTUAL_ENV
61+
/Users/dhellmann/.virtualenvs/pymotw
62+
$ cdvirtualenv
63+
$ pwd
64+
/Users/dhellmann/.virtualenvs/pymotw
65+
$ cdvirtualenv bin
66+
$ pwd
67+
/Users/dhellmann/.virtualenvs/pymotw/bin
68+
69+
cdsitepackages
70+
--------------
71+
72+
Because the exact path to the site-packages directory in the virtualenv depends on the
73+
version of Python, ``cdsitepackages`` is provided as a shortcut for ``cdvirtualenv
74+
lib/python${pyvers}/site-packages``.
75+
76+
===============
77+
Path Management
78+
===============
79+
80+
Sometimes it is desirable to share installed packages that are not in the system ``site-pacakges`` directory and which you do not want to install in each virtualenv. In this case, you *could* symlink the source into the environment ``site-packages`` directory, but it is also easy to add extra directories to the PYTHONPATH by including them in a .pth file inside ``site-packages`` using ``add2virtualenv``.
81+
82+
1. Check out the source for a big project, such as Django.
83+
2. Run: ``add2virtualenv path_to_source``.
84+
3. Run: ``add2virtualenv``.
85+
4. A usage message and list of current "extra" paths is printed.
86+
87+
add2virtualenv
88+
--------------
89+
90+
Adds the specified directories to the Python path for the currently-active
91+
virtualenv.
92+
93+
Syntax::
94+
95+
add2virtualenv directory1 directory2 ...
96+
97+
Path management for packages outside of the virtual env.
98+
Based on a contribution from James Bennett and Jannis Leidel.
99+
100+
This will be done by placing the directory names in a path file
101+
named ``virtualenv_path_extensions.pth`` inside the virtualenv's site-packages
102+
directory; if this file does not exist, it will be created first.

‎docsource/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,10 +138,10 @@
138138
#html_additional_pages = {}
139139

140140
# If false, no module index is generated.
141-
#html_use_modindex = True
141+
html_use_modindex = False
142142

143143
# If false, no index is generated.
144-
#html_use_index = True
144+
html_use_index = False
145145

146146
# If true, the index is split into individual pages for each letter.
147147
#html_split_index = False

0 commit comments

Comments
 (0)