Skip to content

Commit a5edf22

Browse files
dhellmanndhellmann
committed
doc updates
1 parent fb90260 commit a5edf22

File tree

5 files changed

+287
-92
lines changed

5 files changed

+287
-92
lines changed

‎docs/source/command_ref.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
.. Quick reference documentation for virtualenvwrapper command line functions
22
Originally contributed Thursday, May 28, 2009 by Steve Steiner ([email protected])
33
4+
.. _command:
5+
46
#################
57
Command Reference
68
#################

‎docs/source/extensions.rst

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,26 @@ templates to virtualenvwrapper.
1616
bitbucket
1717
---------
1818

19-
The bitbucket_ extension creates a project working directory and
19+
The bitbucket_ project template creates a working directory and
2020
automatically clones the repository from BitBucket. Requires
2121
project_.
2222

2323
.. _project: http://www.doughellmann.com/projects/virtualenvwrapper.project/
2424

2525
.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
2626

27+
emacs-desktop
28+
=============
29+
30+
Emacs desktop-mode_ lets you save the state of emacs (open buffers,
31+
kill rings, buffer positions, etc.) between sessions. It can also be
32+
used as a project file similar to other IDEs. The emacs-desktop_
33+
plugin adds a trigger to save the current desktop file and load a new
34+
one when activating a new virtualenv using ``workon``.
35+
36+
.. _desktop-mode: http://www.emacswiki.org/emacs/DeskTop
37+
38+
.. _emacs-desktop: http://www.doughellmann.com/projects/virtualenvwrapper-emacs-desktop/
2739

2840
user_scripts
2941
============

‎docs/source/index.rst

Lines changed: 134 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -29,77 +29,141 @@ Features
2929
:ref:`plugins`).
3030

3131
============
32-
Installation
32+
Introduction
3333
============
3434

35-
WORKON_HOME
36-
===========
37-
38-
The variable ``WORKON_HOME`` tells virtualenvwrapper where to place
39-
your virtual environments. The default is ``$HOME/.virtualenvs``.
40-
This directory must be created before using any virtualenvwrapper
41-
commands.
42-
43-
Shell Startup File
44-
==================
45-
46-
Add two lines to your shell startup file (``.bashrc``, ``.profile``,
47-
etc.) to set the location where the virtual environments should live
48-
and the location of the script installed with this package::
49-
50-
export WORKON_HOME=$HOME/.virtualenvs
51-
source /usr/local/bin/virtualenvwrapper.sh
52-
53-
After editing it, reload the startup file (e.g., run: ``source
54-
~/.bashrc``).
55-
56-
Python Interpreter and $PATH
57-
============================
58-
59-
During startup, ``virtualenvwrapper.sh`` finds the first ``python`` on
60-
the ``$PATH`` and remembers it to use later. This eliminates any
61-
conflict as the ``$PATH`` changes, enabling interpreters inside
62-
virtual environments where virtualenvwrapper is not installed.
63-
Because of this behavior, it is important for the ``$PATH`` to be set
64-
**before** sourcing ``virtualenvwrapper.sh``. For example::
65-
66-
export PATH=/usr/local/bin:$PATH
67-
source /usr/local/bin/virtualenvwrapper.sh
68-
69-
To override the ``$PATH`` search, set the variable
70-
``VIRTUALENVWRAPPER_PYTHON`` to the full path of the interpreter to
71-
use (also **before** sourcing ``virtualenvwrapper.sh``). For
72-
example::
73-
74-
export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
75-
source /usr/local/bin/virtualenvwrapper.sh
76-
77-
Quick-Start
78-
===========
79-
80-
1. Run: ``workon``
81-
2. A list of environments, empty, is printed.
82-
3. Run: ``mkvirtualenv temp``
83-
4. A new environment, ``temp`` is created and activated.
84-
5. Run: ``workon``
85-
6. This time, the ``temp`` environment is included.
86-
87-
Temporary Files
88-
===============
89-
90-
virtualenvwrapper creates temporary files in ``$TMPDIR``. If the
91-
variable is not set, it uses ``/tmp``. To change the location of
92-
temporary files just for virtualenvwrapper, set
93-
``VIRTUALENVWRAPPER_TMPDIR``.
94-
95-
Upgrading from 1.x
96-
==================
97-
98-
The shell script containing the wrapper functions has been renamed in
99-
the 2.x series to reflect the fact that shells other than bash are
100-
supported. In your startup file, change ``source
101-
/usr/local/bin/virtualenvwrapper_bashrc`` to ``source
102-
/usr/local/bin/virtualenvwrapper.sh``.
35+
The best way to explain the features virtualenvwrapper gives you is to
36+
show it in use.
37+
38+
First, some initialization steps. Most of this only needs to be done
39+
one time. You will want to add the command to ``source
40+
/usr/local/bin/virtualenvwrapper.sh`` to your shell startup file,
41+
changing the path to virtualenvwrapper.sh depending on where it was
42+
installed by pip.
43+
44+
::
45+
46+
$ pip install virtualenvwrapper
47+
...
48+
$ export WORKON_HOME=~/Envs
49+
$ mkdir -p $WORKON_HOME
50+
$ source /usr/local/bin/virtualenvwrapper.sh
51+
$ mkvirtualenv env1
52+
Installing
53+
distribute..........................................
54+
....................................................
55+
....................................................
56+
...............................done.
57+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/predeactivate
58+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/postdeactivate
59+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/preactivate
60+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/postactivate New python executable in env1/bin/python
61+
(env1)$ ls $WORKON_HOME
62+
env1 hook.log
63+
64+
Now we can install some software into the environment.
65+
66+
::
67+
68+
(env1)$ pip install django
69+
Downloading/unpacking django
70+
Downloading Django-1.1.1.tar.gz (5.6Mb): 5.6Mb downloaded
71+
Running setup.py egg_info for package django
72+
Installing collected packages: django
73+
Running setup.py install for django
74+
changing mode of build/scripts-2.6/django-admin.py from 644 to 755
75+
changing mode of /Users/dhellmann/Envs/env1/bin/django-admin.py to 755
76+
Successfully installed django
77+
78+
We can see the new package with ``lssitepackages``::
79+
80+
(env1)$ lssitepackages
81+
Django-1.1.1-py2.6.egg-info easy-install.pth
82+
distribute-0.6.10-py2.6.egg pip-0.6.3-py2.6.egg
83+
django setuptools.pth
84+
85+
Of course we are not limited to a single virtualenv::
86+
87+
(env1)$ ls $WORKON_HOME
88+
env1 hook.log
89+
(env1)$ mkvirtualenv env2
90+
Installing distribute...............................
91+
....................................................
92+
....................................................
93+
........... ...............................done.
94+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/predeactivate
95+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/postdeactivate
96+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/preactivate
97+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/postactivate New python executable in env2/bin/python
98+
(env2)$ ls $WORKON_HOME
99+
env1 env2 hook.log
100+
101+
Switch between environments with ``workon``::
102+
103+
(env2)$ workon env1
104+
(env1)$ echo $VIRTUAL_ENV
105+
/Users/dhellmann/Envs/env1
106+
(env1)$
107+
108+
The ``workon`` command also includes tab completion for the
109+
environment names, and invokes customization scripts as an environment
110+
is activated or deactivated (see :ref:`scripts`).
111+
112+
::
113+
114+
(env1)$ echo 'cd $VIRTUAL_ENV' >> $WORKON_HOME/postactivate
115+
(env1)$ workon env2
116+
(env2)$ pwd
117+
/Users/dhellmann/Envs/env2
118+
119+
:ref:`scripts-postmkvirtualenv` is run when a new environment is
120+
created, letting you automatically install commonly-used tools.
121+
122+
::
123+
124+
(env2)$ echo 'pip install sphinx' >> $WORKON_HOME/postmkvirtualenv
125+
(env3)$ mkvirtualenv env3
126+
New python executable in env3/bin/python
127+
Installing distribute...............................
128+
....................................................
129+
....................................................
130+
........... ...............................done.
131+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/predeactivate
132+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/postdeactivate
133+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/preactivate
134+
virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/postactivate
135+
Downloading/unpacking sphinx
136+
Downloading Sphinx-0.6.5.tar.gz (972Kb): 972Kb downloaded
137+
Running setup.py egg_info for package sphinx
138+
no previously-included directories found matching 'doc/_build'
139+
Downloading/unpacking Pygments>=0.8 (from sphinx)
140+
Downloading Pygments-1.3.1.tar.gz (1.1Mb): 1.1Mb downloaded
141+
Running setup.py egg_info for package Pygments
142+
Downloading/unpacking Jinja2>=2.1 (from sphinx)
143+
Downloading Jinja2-2.4.tar.gz (688Kb): 688Kb downloaded
144+
Running setup.py egg_info for package Jinja2
145+
warning: no previously-included files matching '*' found under directory 'docs/_build/doctrees'
146+
Downloading/unpacking docutils>=0.4 (from sphinx)
147+
Downloading docutils-0.6.tar.gz (1.4Mb): 1.4Mb downloaded
148+
Running setup.py egg_info for package docutils
149+
Installing collected packages: docutils, Jinja2, Pygments, sphinx
150+
Running setup.py install for docutils
151+
Running setup.py install for Jinja2
152+
Running setup.py install for Pygments
153+
Running setup.py install for sphinx
154+
no previously-included directories found matching 'doc/_build'
155+
Installing sphinx-build script to /Users/dhellmann/Envs/env3/bin
156+
Installing sphinx-quickstart script to /Users/dhellmann/Envs/env3/bin
157+
Installing sphinx-autogen script to /Users/dhellmann/Envs/env3/bin
158+
Successfully installed docutils Jinja2 Pygments sphinx (env3)$
159+
(venv3)$ which sphinx-build
160+
/Users/dhellmann/Envs/env3/bin/sphinx-build
161+
162+
Through a combination of the existing functions defined by the core
163+
package (see :ref:`command`), third-party plugins (see
164+
:ref:`plugins`), and user-defined scripts (see :ref:`scripts`)
165+
virtualenvwrapper gives you a wide variety of opportunities to
166+
automate repetitive operations.
103167

104168
=======
105169
Details
@@ -108,6 +172,7 @@ Details
108172
.. toctree::
109173
:maxdepth: 2
110174

175+
install
111176
command_ref
112177
hooks
113178
tips

‎docs/source/install.rst

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
============
2+
Installation
3+
============
4+
5+
WORKON_HOME
6+
===========
7+
8+
The variable ``WORKON_HOME`` tells virtualenvwrapper where to place
9+
your virtual environments. The default is ``$HOME/.virtualenvs``.
10+
This directory must be created before using any virtualenvwrapper
11+
commands.
12+
13+
Shell Startup File
14+
==================
15+
16+
Add two lines to your shell startup file (``.bashrc``, ``.profile``,
17+
etc.) to set the location where the virtual environments should live
18+
and the location of the script installed with this package::
19+
20+
export WORKON_HOME=$HOME/.virtualenvs
21+
source /usr/local/bin/virtualenvwrapper.sh
22+
23+
After editing it, reload the startup file (e.g., run: ``source
24+
~/.bashrc``).
25+
26+
Python Interpreter and $PATH
27+
============================
28+
29+
During startup, ``virtualenvwrapper.sh`` finds the first ``python`` on
30+
the ``$PATH`` and remembers it to use later. This eliminates any
31+
conflict as the ``$PATH`` changes, enabling interpreters inside
32+
virtual environments where virtualenvwrapper is not installed.
33+
Because of this behavior, it is important for the ``$PATH`` to be set
34+
**before** sourcing ``virtualenvwrapper.sh``. For example::
35+
36+
export PATH=/usr/local/bin:$PATH
37+
source /usr/local/bin/virtualenvwrapper.sh
38+
39+
To override the ``$PATH`` search, set the variable
40+
``VIRTUALENVWRAPPER_PYTHON`` to the full path of the interpreter to
41+
use (also **before** sourcing ``virtualenvwrapper.sh``). For
42+
example::
43+
44+
export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
45+
source /usr/local/bin/virtualenvwrapper.sh
46+
47+
Quick-Start
48+
===========
49+
50+
1. Run: ``workon``
51+
2. A list of environments, empty, is printed.
52+
3. Run: ``mkvirtualenv temp``
53+
4. A new environment, ``temp`` is created and activated.
54+
5. Run: ``workon``
55+
6. This time, the ``temp`` environment is included.
56+
57+
Temporary Files
58+
===============
59+
60+
virtualenvwrapper creates temporary files in ``$TMPDIR``. If the
61+
variable is not set, it uses ``/tmp``. To change the location of
62+
temporary files just for virtualenvwrapper, set
63+
``VIRTUALENVWRAPPER_TMPDIR``.
64+
65+
Upgrading from 1.x
66+
==================
67+
68+
The shell script containing the wrapper functions has been renamed in
69+
the 2.x series to reflect the fact that shells other than bash are
70+
supported. In your startup file, change ``source
71+
/usr/local/bin/virtualenvwrapper_bashrc`` to ``source
72+
/usr/local/bin/virtualenvwrapper.sh``.

0 commit comments

Comments
 (0)