Commits

Doug Hellmann committed 2c46edf

start overhauling doc content

Comments (0)

Files changed (7)

docs/source/command_ref.rst

 
 (any options are passed directly to ``virtualenv``)
 
+.. seealso::
+
+   * :ref:`hooks-scripts-premkvirtualenv`
+   * :ref:`hooks-scripts-postmkvirtualenv`
+
 rmvirtualenv
 ------------
 
 
     rmvirtualenv ENVNAME
 
+.. seealso::
+
+   * :ref:`hooks-scripts-prermvirtualenv`
+   * :ref:`hooks-scripts-postrmvirtualenv`
+
 cpvirtualenv
 ------------
 
 If no ``environment_name`` is given the list of available environments
 is printed to stdout.
 
+.. seealso::
+
+   * :ref:`hooks-scripts-predeactivate`
+   * :ref:`hooks-scripts-postdeactivate`
+   * :ref:`hooks-scripts-preactivate`
+   * :ref:`hooks-scripts-postactivate`
+
 deactivate
 ----------
 
     This command is actually part of virtualenv, but is wrapped to
     provide before and after hooks, just as workon does for activate.
 
+.. seealso::
+
+   * :ref:`hooks-scripts-predeactivate`
+   * :ref:`hooks-scripts-postdeactivate`
+
 ==================================
 Quickly Navigating to a virtualenv
 ==================================

docs/source/developers.rst

 <http://shunit2.googlecode.com/>`_.  To run the tests under bash, sh,
 and zsh, use ``make test``.  To add new tests, modify or create an
 appropriate script in the ``tests`` directory.
+
+.. _developers-extensions:
+
+Creating Extension Plugins
+==========================
+
+virtualenvwrapper adds several hook points you can use to modify its
+behavior.  End-users can provide simple shell scripts (see
+:ref:`hook-scripts`).  Extensions can also be implemented in Python by
+using the ``setuptools`` style *entry points*.
+
+Types of Hooks
+--------------
+
+Existing Hook Points
+--------------------
+

docs/source/extensions.rst

+=====================
+ Existing Extensions
+=====================
+
+make_hooks
+
+user_scripts

docs/source/hooks.rst

-============
-Hook Scripts
-============
+===============================
+ Customizing Virtualenvwrapper
+===============================
 
 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. They are either
-*sourced* (allowing them to modify your shell environment) or *run* as
-an external program at the appropriate trigger time.
+creating, deleting, or moving between environments. These hooks are
+exposed in two ways:
 
-Environment Hooks
-=================
+.. toctree::
+   :maxdepth: 1
 
-postactivate
-------------
-
-The ``$VIRTUAL_ENV/bin/postactivate`` script is sourced after the new
-environment is enabled. ``$VIRTUAL_ENV`` refers to the new environment
-at the time the script runs.
-
-This example script for the PyMOTW environment changes the current
-working directory and the PATH variable to refer to the source tree
-containing the PyMOTW source.
-
-::
-
-    pymotw_root=/Users/dhellmann/Documents/PyMOTW
-    cd $pymotw_root
-    PATH=$pymotw_root/bin:$PATH
-
-predeactivate
--------------
-
-The ``$VIRTUAL_ENV/bin/predeactivate`` script is sourced before the
-current environment is deactivated, and can be used to disable or
-clear settings in your environment. ``$VIRTUAL_ENV`` refers to the old
-environment at the time the script runs.
-
-Global Hooks
-============
-
-postactivate
-------------
-
-The global ``$WORKON_HOME/postactivate`` script is sourced after the
-new environment is enabled and the new environment's postactivate is
-sourced (if it exists). ``$VIRTUAL_ENV`` refers to the new environment
-at the time the script runs.
-
-This example script adds a space between the virtual environment name
-and your old PS1 by making use of ``_OLD_VIRTUAL_PS1``.
-
-::
-
-    PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"
-
-premkvirtualenv
----------------
-
-The ``$WORKON_HOME/premkvirtualenv`` script is run as an external
-program after the virtual environment is created but before the
-current environment is switched to point to the new env. The current
-working directory for the script is ``$WORKON_HOME`` and the name of
-the new environment is passed as an argument to the script.
-
-postmkvirtualenv
-----------------
-
-The ``$WORKON_HOME/postmkvirtualenv`` script is sourced after the new
-environment is created and activated.
-
-prermvirtualenv
----------------
-
-The ``$WORKON_HOME/prermvirtualenv`` script is run as an external
-program before the environment is removed. The full path to the
-environment directory is passed as an argument to the script.
-
-postrmvirtualenv
-----------------
-
-The ``$WORKON_HOME/postrmvirtualenv`` script is run as an external
-program after the environment is removed. The full path to the
-environment directory is passed as an argument to the script.
+   scripts
+   plugins

docs/source/index.rst

    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-#################
-virtualenvwrapper
-#################
+###########################
+virtualenvwrapper |release|
+###########################
 
 virtualenvwrapper is a set of extensions to Ian Bicking's `virtualenv
 <http://pypi.python.org/pypi/virtualenv>`_ tool.  The extensions
    tips
    history
    developers
+   extensions
 
 .. _references:
 

docs/source/plugins.rst

+.. _developers-extensions:
+
+===================
+ Extension Plugins
+===================
+
+virtualenvwrapper adds several hook points you can use to modify its
+behavior.  End-users can provide simple shell scripts (see
+:ref:`hook-scripts`).  Extensions can also be implemented in Python by
+using the ``setuptools`` style *entry points*.
+
+Types of Hooks
+--------------
+
+Existing Hook Points
+--------------------
+
+Logging
+-------

docs/source/scripts.rst

+.. _hooks-scripts:
+
+Per-User Hook Scripts
+=====================
+
+The end-user customization scripts are either *sourced* (allowing them
+to modify your shell environment) or *run* as an external program at
+the appropriate trigger time.
+
+.. _hooks-scripts-initialize:
+
+initialize
+----------
+
+  :Global/Local: global
+  :Argument(s): None
+  :Sourced/Run: run
+
+``$WORKON_HOME/initialize`` is sourced when ``virtualenvwrapper.sh``
+is loaded into your environment.  Use it to adjust global settings
+when virtualenvwrapper is enabled.
+
+.. _hooks-scripts-premkvirtualenv:
+
+premkvirtualenv
+---------------
+
+  :Global/Local: global
+  :Argument(s): name of new environment
+  :Sourced/Run: run
+
+``$WORKON_HOME/premkvirtualenv`` is run as an external program after
+the virtual environment is created but before the current environment
+is switched to point to the new env. The current working directory for
+the script is ``$WORKON_HOME`` and the name of the new environment is
+passed as an argument to the script.
+
+.. _hooks-scripts-postmkvirtualenv:
+
+postmkvirtualenv
+----------------
+
+  :Global/Local: global
+  :Argument(s): none
+  :Sourced/Run: sourced
+
+``$WORKON_HOME/postmkvirtualenv`` is sourced after the new environment
+is created and activated.
+
+.. _hooks-scripts-preactivate:
+
+preactivate
+-----------
+
+  :Global/Local: global, local
+  :Argument(s): environment name
+  :Sourced/Run: run
+
+The global ``$WORKON_HOME/preactivate`` script is run before the new
+environment is enabled.  The environment name is passed as the first
+argument.
+
+The local ``$VIRTUAL_ENV/bin/preactivate`` hook is run before the new
+environment is enabled.  The environment name is passed as the first
+argument.
+
+.. _hooks-scripts-postactivate:
+
+postactivate
+------------
+
+  :Global/Local: global, local
+  :Argument(s): none
+  :Sourced/Run: sourced
+
+The global ``$WORKON_HOME/postactivate`` script is sourced after the
+new environment is enabled. ``$VIRTUAL_ENV`` refers to the new
+environment at the time the script runs.
+
+This example script adds a space between the virtual environment name
+and your old PS1 by making use of ``_OLD_VIRTUAL_PS1``.
+
+::
+
+    PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"
+
+The local ``$VIRTUAL_ENV/bin/postactivate`` script is sourced after
+the new environment is enabled. ``$VIRTUAL_ENV`` refers to the new
+environment at the time the script runs.
+
+This example script for the PyMOTW environment changes the current
+working directory and the PATH variable to refer to the source tree
+containing the PyMOTW source.
+
+::
+
+    pymotw_root=/Users/dhellmann/Documents/PyMOTW
+    cd $pymotw_root
+    PATH=$pymotw_root/bin:$PATH
+
+.. _hooks-scripts-predeactivate:
+
+predeactivate
+-------------
+
+  :Global/Local: local, global
+  :Argument(s): none
+  :Sourced/Run: sourced
+
+The local ``$VIRTUAL_ENV/bin/predeactivate`` script is sourced before the
+current environment is deactivated, and can be used to disable or
+clear settings in your environment. ``$VIRTUAL_ENV`` refers to the old
+environment at the time the script runs.
+
+The global ``$WORKON_HOME/predeactivate`` script is sourced before the
+current environment is deactivated.  ``$VIRTUAL_ENV`` refers to the
+old environment at the time the script runs.
+
+.. _hooks-scripts-postdeactivate:
+
+postdeactivate
+--------------
+
+  :Global/Local: local, global
+  :Argument(s): none
+  :Sourced/Run: sourced
+
+The ``$VIRTUAL_ENV/bin/postdeactivate`` script is sourced after the
+current environment is deactivated, and can be used to disable or
+clear settings in your environment.  The path to the environment just
+deactivated is available in ``$VIRTUALENVWRAPPER_LAST_VIRTUALENV``.
+
+.. _hooks-scripts-prermvirtualenv:
+
+prermvirtualenv
+---------------
+
+  :Global/Local: global
+  :Argument(s): environment name
+  :Sourced/Run: run
+
+The ``$WORKON_HOME/prermvirtualenv`` script is run as an external
+program before the environment is removed. The full path to the
+environment directory is passed as an argument to the script.
+
+.. _hooks-scripts-postrmvirtualenv:
+
+postrmvirtualenv
+----------------
+
+  :Global/Local: global
+  :Argument(s): environment name
+  :Sourced/Run: run
+
+The ``$WORKON_HOME/postrmvirtualenv`` script is run as an external
+program after the environment is removed. The full path to the
+environment directory is passed as an argument to the script.