Skip to content

Commit 2c46edf

Browse files
dhellmanndhellmann
committed
start overhauling doc content
1 parent 6473099 commit 2c46edf

File tree

7 files changed

+235
-82
lines changed

7 files changed

+235
-82
lines changed

‎docs/source/command_ref.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@ Syntax::
2222

2323
(any options are passed directly to ``virtualenv``)
2424

25+
.. seealso::
26+
27+
* :ref:`hooks-scripts-premkvirtualenv`
28+
* :ref:`hooks-scripts-postmkvirtualenv`
29+
2530
rmvirtualenv
2631
------------
2732

@@ -31,6 +36,11 @@ Syntax::
3136

3237
rmvirtualenv ENVNAME
3338

39+
.. seealso::
40+
41+
* :ref:`hooks-scripts-prermvirtualenv`
42+
* :ref:`hooks-scripts-postrmvirtualenv`
43+
3444
cpvirtualenv
3545
------------
3646

@@ -57,6 +67,13 @@ Syntax::
5767
If no ``environment_name`` is given the list of available environments
5868
is printed to stdout.
5969

70+
.. seealso::
71+
72+
* :ref:`hooks-scripts-predeactivate`
73+
* :ref:`hooks-scripts-postdeactivate`
74+
* :ref:`hooks-scripts-preactivate`
75+
* :ref:`hooks-scripts-postactivate`
76+
6077
deactivate
6178
----------
6279

@@ -72,6 +89,11 @@ Syntax::
7289
This command is actually part of virtualenv, but is wrapped to
7390
provide before and after hooks, just as workon does for activate.
7491

92+
.. seealso::
93+
94+
* :ref:`hooks-scripts-predeactivate`
95+
* :ref:`hooks-scripts-postdeactivate`
96+
7597
==================================
7698
Quickly Navigating to a virtualenv
7799
==================================

‎docs/source/developers.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,3 +63,20 @@ The test suite for virtualenvwrapper uses `shunit2
6363
<http://shunit2.googlecode.com/>`_. To run the tests under bash, sh,
6464
and zsh, use ``make test``. To add new tests, modify or create an
6565
appropriate script in the ``tests`` directory.
66+
67+
.. _developers-extensions:
68+
69+
Creating Extension Plugins
70+
==========================
71+
72+
virtualenvwrapper adds several hook points you can use to modify its
73+
behavior. End-users can provide simple shell scripts (see
74+
:ref:`hook-scripts`). Extensions can also be implemented in Python by
75+
using the ``setuptools`` style *entry points*.
76+
77+
Types of Hooks
78+
--------------
79+
80+
Existing Hook Points
81+
--------------------
82+

‎docs/source/extensions.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
=====================
2+
Existing Extensions
3+
=====================
4+
5+
make_hooks
6+
7+
user_scripts

‎docs/source/hooks.rst

Lines changed: 9 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,14 @@
1-
============
2-
Hook Scripts
3-
============
1+
===============================
2+
Customizing Virtualenvwrapper
3+
===============================
44

55
virtualenvwrapper adds several hook points you can use to change your
66
settings, shell environment, or other configuration values when
7-
creating, deleting, or moving between environments. They are either
8-
*sourced* (allowing them to modify your shell environment) or *run* as
9-
an external program at the appropriate trigger time.
7+
creating, deleting, or moving between environments. These hooks are
8+
exposed in two ways:
109

11-
Environment Hooks
12-
=================
10+
.. toctree::
11+
:maxdepth: 1
1312

14-
postactivate
15-
------------
16-
17-
The ``$VIRTUAL_ENV/bin/postactivate`` script is sourced after the new
18-
environment is enabled. ``$VIRTUAL_ENV`` refers to the new environment
19-
at the time the script runs.
20-
21-
This example script for the PyMOTW environment changes the current
22-
working directory and the PATH variable to refer to the source tree
23-
containing the PyMOTW source.
24-
25-
::
26-
27-
pymotw_root=/Users/dhellmann/Documents/PyMOTW
28-
cd $pymotw_root
29-
PATH=$pymotw_root/bin:$PATH
30-
31-
predeactivate
32-
-------------
33-
34-
The ``$VIRTUAL_ENV/bin/predeactivate`` script is sourced before the
35-
current environment is deactivated, and can be used to disable or
36-
clear settings in your environment. ``$VIRTUAL_ENV`` refers to the old
37-
environment at the time the script runs.
38-
39-
Global Hooks
40-
============
41-
42-
postactivate
43-
------------
44-
45-
The global ``$WORKON_HOME/postactivate`` script is sourced after the
46-
new environment is enabled and the new environment's postactivate is
47-
sourced (if it exists). ``$VIRTUAL_ENV`` refers to the new environment
48-
at the time the script runs.
49-
50-
This example script adds a space between the virtual environment name
51-
and your old PS1 by making use of ``_OLD_VIRTUAL_PS1``.
52-
53-
::
54-
55-
PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"
56-
57-
premkvirtualenv
58-
---------------
59-
60-
The ``$WORKON_HOME/premkvirtualenv`` script is run as an external
61-
program after the virtual environment is created but before the
62-
current environment is switched to point to the new env. The current
63-
working directory for the script is ``$WORKON_HOME`` and the name of
64-
the new environment is passed as an argument to the script.
65-
66-
postmkvirtualenv
67-
----------------
68-
69-
The ``$WORKON_HOME/postmkvirtualenv`` script is sourced after the new
70-
environment is created and activated.
71-
72-
prermvirtualenv
73-
---------------
74-
75-
The ``$WORKON_HOME/prermvirtualenv`` script is run as an external
76-
program before the environment is removed. The full path to the
77-
environment directory is passed as an argument to the script.
78-
79-
postrmvirtualenv
80-
----------------
81-
82-
The ``$WORKON_HOME/postrmvirtualenv`` script is run as an external
83-
program after the environment is removed. The full path to the
84-
environment directory is passed as an argument to the script.
13+
scripts
14+
plugins

‎docs/source/index.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
#################
7-
virtualenvwrapper
8-
#################
6+
###########################
7+
virtualenvwrapper |release|
8+
###########################
99

1010
virtualenvwrapper is a set of extensions to Ian Bicking's `virtualenv
1111
<http://pypi.python.org/pypi/virtualenv>`_ tool. The extensions
@@ -68,6 +68,7 @@ Details
6868
tips
6969
history
7070
developers
71+
extensions
7172

7273
.. _references:
7374

‎docs/source/plugins.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. _developers-extensions:
2+
3+
===================
4+
Extension Plugins
5+
===================
6+
7+
virtualenvwrapper adds several hook points you can use to modify its
8+
behavior. End-users can provide simple shell scripts (see
9+
:ref:`hook-scripts`). Extensions can also be implemented in Python by
10+
using the ``setuptools`` style *entry points*.
11+
12+
Types of Hooks
13+
--------------
14+
15+
Existing Hook Points
16+
--------------------
17+
18+
Logging
19+
-------

‎docs/source/scripts.rst

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
.. _hooks-scripts:
2+
3+
Per-User Hook Scripts
4+
=====================
5+
6+
The end-user customization scripts are either *sourced* (allowing them
7+
to modify your shell environment) or *run* as an external program at
8+
the appropriate trigger time.
9+
10+
.. _hooks-scripts-initialize:
11+
12+
initialize
13+
----------
14+
15+
:Global/Local: global
16+
:Argument(s): None
17+
:Sourced/Run: run
18+
19+
``$WORKON_HOME/initialize`` is sourced when ``virtualenvwrapper.sh``
20+
is loaded into your environment. Use it to adjust global settings
21+
when virtualenvwrapper is enabled.
22+
23+
.. _hooks-scripts-premkvirtualenv:
24+
25+
premkvirtualenv
26+
---------------
27+
28+
:Global/Local: global
29+
:Argument(s): name of new environment
30+
:Sourced/Run: run
31+
32+
``$WORKON_HOME/premkvirtualenv`` is run as an external program after
33+
the virtual environment is created but before the current environment
34+
is switched to point to the new env. The current working directory for
35+
the script is ``$WORKON_HOME`` and the name of the new environment is
36+
passed as an argument to the script.
37+
38+
.. _hooks-scripts-postmkvirtualenv:
39+
40+
postmkvirtualenv
41+
----------------
42+
43+
:Global/Local: global
44+
:Argument(s): none
45+
:Sourced/Run: sourced
46+
47+
``$WORKON_HOME/postmkvirtualenv`` is sourced after the new environment
48+
is created and activated.
49+
50+
.. _hooks-scripts-preactivate:
51+
52+
preactivate
53+
-----------
54+
55+
:Global/Local: global, local
56+
:Argument(s): environment name
57+
:Sourced/Run: run
58+
59+
The global ``$WORKON_HOME/preactivate`` script is run before the new
60+
environment is enabled. The environment name is passed as the first
61+
argument.
62+
63+
The local ``$VIRTUAL_ENV/bin/preactivate`` hook is run before the new
64+
environment is enabled. The environment name is passed as the first
65+
argument.
66+
67+
.. _hooks-scripts-postactivate:
68+
69+
postactivate
70+
------------
71+
72+
:Global/Local: global, local
73+
:Argument(s): none
74+
:Sourced/Run: sourced
75+
76+
The global ``$WORKON_HOME/postactivate`` script is sourced after the
77+
new environment is enabled. ``$VIRTUAL_ENV`` refers to the new
78+
environment at the time the script runs.
79+
80+
This example script adds a space between the virtual environment name
81+
and your old PS1 by making use of ``_OLD_VIRTUAL_PS1``.
82+
83+
::
84+
85+
PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"
86+
87+
The local ``$VIRTUAL_ENV/bin/postactivate`` script is sourced after
88+
the new environment is enabled. ``$VIRTUAL_ENV`` refers to the new
89+
environment at the time the script runs.
90+
91+
This example script for the PyMOTW environment changes the current
92+
working directory and the PATH variable to refer to the source tree
93+
containing the PyMOTW source.
94+
95+
::
96+
97+
pymotw_root=/Users/dhellmann/Documents/PyMOTW
98+
cd $pymotw_root
99+
PATH=$pymotw_root/bin:$PATH
100+
101+
.. _hooks-scripts-predeactivate:
102+
103+
predeactivate
104+
-------------
105+
106+
:Global/Local: local, global
107+
:Argument(s): none
108+
:Sourced/Run: sourced
109+
110+
The local ``$VIRTUAL_ENV/bin/predeactivate`` script is sourced before the
111+
current environment is deactivated, and can be used to disable or
112+
clear settings in your environment. ``$VIRTUAL_ENV`` refers to the old
113+
environment at the time the script runs.
114+
115+
The global ``$WORKON_HOME/predeactivate`` script is sourced before the
116+
current environment is deactivated. ``$VIRTUAL_ENV`` refers to the
117+
old environment at the time the script runs.
118+
119+
.. _hooks-scripts-postdeactivate:
120+
121+
postdeactivate
122+
--------------
123+
124+
:Global/Local: local, global
125+
:Argument(s): none
126+
:Sourced/Run: sourced
127+
128+
The ``$VIRTUAL_ENV/bin/postdeactivate`` script is sourced after the
129+
current environment is deactivated, and can be used to disable or
130+
clear settings in your environment. The path to the environment just
131+
deactivated is available in ``$VIRTUALENVWRAPPER_LAST_VIRTUALENV``.
132+
133+
.. _hooks-scripts-prermvirtualenv:
134+
135+
prermvirtualenv
136+
---------------
137+
138+
:Global/Local: global
139+
:Argument(s): environment name
140+
:Sourced/Run: run
141+
142+
The ``$WORKON_HOME/prermvirtualenv`` script is run as an external
143+
program before the environment is removed. The full path to the
144+
environment directory is passed as an argument to the script.
145+
146+
.. _hooks-scripts-postrmvirtualenv:
147+
148+
postrmvirtualenv
149+
----------------
150+
151+
:Global/Local: global
152+
:Argument(s): environment name
153+
:Sourced/Run: run
154+
155+
The ``$WORKON_HOME/postrmvirtualenv`` script is run as an external
156+
program after the environment is removed. The full path to the
157+
environment directory is passed as an argument to the script.

0 commit comments

Comments
 (0)