Merged in jessamynsmith/virtualenvwrapper (pull request #23)

Reworded the documentation around user scripts vs plugin creation

Author: dhellmann

docs/source/hooks.rst

@@ -5,7 +5,10 @@
 virtualenvwrapper adds several hook points you can use to change your
 settings, shell environment, or other configuration values when
 creating, deleting, or moving between environments. These hooks are
-exposed in two ways:
+exposed in two ways. :ref:`scripts` allows a user to perform generic actions
+for every virtualenv in your environment, including customization of
+virtualenv creation. :ref:`plugins` makes it possible to share common
+behaviors between systems and developers.
 
 .. toctree::
    :maxdepth: 1

docs/source/plugins.rst

@@ -12,6 +12,13 @@ virtualenvwrapper continues the tradition of encouraging a craftsman
 to modify their tools to work the way they want, rather than the other
 way around.
 
+There are two ways to attach your code so that virtualenvwrapper will
+run it: End-users can use shell scripts or other programs for personal
+customization, e.g. automatically performing an action on every new
+virtualenv (see :ref:`scripts`).  Extensions can also be
+implemented in Python by using Distribute_ *entry points*, making it
+possible to share common behaviors between systems and developers.
+
 Use the hooks provided to eliminate repetitive manual operations and
 streamline your development workflow.  For example, set up the
 :ref:`plugins-pre_activate` and :ref:`plugins-post_activate` hooks to
@@ -25,12 +32,6 @@ install basic requirements into each new development environment,
 initialize a source code control repository, or otherwise set up a new
 project.
 
-There are two ways to attach your code so that virtualenvwrapper will
-run it: End-users can use shell scripts or other programs for personal
-customization (see :ref:`scripts`).  Extensions can also be
-implemented in Python by using Distribute_ *entry points*, making it
-possible to share common behaviors between systems and developers.
-
 Defining an Extension
 =====================
 

docs/source/scripts.rst

@@ -10,9 +10,29 @@ the appropriate trigger time.
 
 The global scripts applied to all environments should be placed in the
 directory named by :ref:`VIRTUALENVWRAPPER_HOOK_DIR
-<variable-VIRTUALENVWRAPPER_HOOK_DIR>`. The local scripts should be
+<variable-VIRTUALENVWRAPPER_HOOK_DIR>`, which by default will be equal
+to :ref:`WORKON_HOME <variable-WORKON_HOME>`. The local scripts should be
 placed in the ``bin`` directory of the virtualenv.
 
+Example Usage
+===============
+
+As a Django developer, you likely want DJANGO_SETTINGS_MODULE to be set, and
+if you work on multiple projects, you want it to be specific to the project
+you are currently working on. Wouldn't it be nice if it was set based on the
+active virtualenv? You can achieve this with :ref:`scripts` as follows.
+
+If your :ref:`WORKON_HOME <variable-WORKON_HOME>` is set to ~/.virtualenvs:
+
+    vim ~/.virtualenvs/premkvirtualenv
+
+Edit the file so it contains the following (for a default Django setup):
+
+    # Automatically set django settings for the virtualenv
+    echo "export DJANGO_SETTINGS_MODULE=$1.settings" >> "$1/bin/activate"
+
+Create a new virtualenv, and you should see DJANGO_SETTINGS_MODULE in your env!
+
 .. _scripts-get_env_details:
 
 get_env_details