Doug Hellmann avatar Doug Hellmann committed a5edf22

doc updates

Comments (0)

Files changed (5)

docs/source/command_ref.rst

 .. Quick reference documentation for virtualenvwrapper command line functions
     Originally contributed Thursday, May 28, 2009 by Steve Steiner (ssteinerX@gmail.com)
 
+.. _command:
+
 #################
 Command Reference
 #################

docs/source/extensions.rst

 bitbucket
 ---------
 
-The bitbucket_ extension creates a project working directory and
+The bitbucket_ project template creates a working directory and
 automatically clones the repository from BitBucket.  Requires
 project_.
 
 
 .. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
 
+emacs-desktop
+=============
+
+Emacs desktop-mode_ lets you save the state of emacs (open buffers,
+kill rings, buffer positions, etc.) between sessions.  It can also be
+used as a project file similar to other IDEs.  The emacs-desktop_
+plugin adds a trigger to save the current desktop file and load a new
+one when activating a new virtualenv using ``workon``.
+
+.. _desktop-mode: http://www.emacswiki.org/emacs/DeskTop
+
+.. _emacs-desktop: http://www.doughellmann.com/projects/virtualenvwrapper-emacs-desktop/
 
 user_scripts
 ============

docs/source/index.rst

    :ref:`plugins`).
 
 ============
-Installation
+Introduction
 ============
 
-WORKON_HOME
-===========
-
-The variable ``WORKON_HOME`` tells virtualenvwrapper where to place
-your virtual environments.  The default is ``$HOME/.virtualenvs``.
-This directory must be created before using any virtualenvwrapper
-commands.
-
-Shell Startup File
-==================
-
-Add two lines to your shell startup file (``.bashrc``, ``.profile``,
-etc.) to set the location where the virtual environments should live
-and the location of the script installed with this package::
-
-    export WORKON_HOME=$HOME/.virtualenvs
-    source /usr/local/bin/virtualenvwrapper.sh
-
-After editing it, reload the startup file (e.g., run: ``source
-~/.bashrc``).
-
-Python Interpreter and $PATH
-============================
-
-During startup, ``virtualenvwrapper.sh`` finds the first ``python`` on
-the ``$PATH`` and remembers it to use later.  This eliminates any
-conflict as the ``$PATH`` changes, enabling interpreters inside
-virtual environments where virtualenvwrapper is not installed.
-Because of this behavior, it is important for the ``$PATH`` to be set
-**before** sourcing ``virtualenvwrapper.sh``.  For example::
-
-    export PATH=/usr/local/bin:$PATH
-    source /usr/local/bin/virtualenvwrapper.sh
-
-To override the ``$PATH`` search, set the variable
-``VIRTUALENVWRAPPER_PYTHON`` to the full path of the interpreter to
-use (also **before** sourcing ``virtualenvwrapper.sh``).  For
-example::
-
-    export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
-    source /usr/local/bin/virtualenvwrapper.sh
-
-Quick-Start
-===========
-
-1. Run: ``workon``
-2. A list of environments, empty, is printed.
-3. Run: ``mkvirtualenv temp``
-4. A new environment, ``temp`` is created and activated.
-5. Run: ``workon``
-6. This time, the ``temp`` environment is included.
-
-Temporary Files
-===============
-
-virtualenvwrapper creates temporary files in ``$TMPDIR``.  If the
-variable is not set, it uses ``/tmp``.  To change the location of
-temporary files just for virtualenvwrapper, set
-``VIRTUALENVWRAPPER_TMPDIR``.
-
-Upgrading from 1.x
-==================
-
-The shell script containing the wrapper functions has been renamed in
-the 2.x series to reflect the fact that shells other than bash are
-supported.  In your startup file, change ``source
-/usr/local/bin/virtualenvwrapper_bashrc`` to ``source
-/usr/local/bin/virtualenvwrapper.sh``.
+The best way to explain the features virtualenvwrapper gives you is to
+show it in use.
+
+First, some initialization steps.  Most of this only needs to be done
+one time.  You will want to add the command to ``source
+/usr/local/bin/virtualenvwrapper.sh`` to your shell startup file,
+changing the path to virtualenvwrapper.sh depending on where it was
+installed by pip.
+
+::
+
+  $ pip install virtualenvwrapper
+  ...
+  $ export WORKON_HOME=~/Envs
+  $ mkdir -p $WORKON_HOME
+  $ source /usr/local/bin/virtualenvwrapper.sh
+  $ mkvirtualenv env1
+  Installing
+  distribute..........................................
+  ....................................................
+  ....................................................
+  ...............................done.
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/predeactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/postdeactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/preactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env1/bin/postactivate  New python executable in env1/bin/python
+  (env1)$ ls $WORKON_HOME
+  env1 hook.log
+
+Now we can install some software into the environment.
+
+::
+
+  (env1)$ pip install django
+  Downloading/unpacking django
+    Downloading Django-1.1.1.tar.gz (5.6Mb): 5.6Mb downloaded
+    Running setup.py egg_info for package django
+  Installing collected packages: django
+    Running setup.py install for django
+      changing mode of build/scripts-2.6/django-admin.py from 644 to 755
+      changing mode of /Users/dhellmann/Envs/env1/bin/django-admin.py to 755
+  Successfully installed django
+
+We can see the new package with ``lssitepackages``::
+
+  (env1)$ lssitepackages
+  Django-1.1.1-py2.6.egg-info     easy-install.pth
+  distribute-0.6.10-py2.6.egg     pip-0.6.3-py2.6.egg
+  django                          setuptools.pth
+
+Of course we are not limited to a single virtualenv::
+
+  (env1)$ ls $WORKON_HOME
+  env1            hook.log
+  (env1)$ mkvirtualenv env2
+  Installing distribute...............................
+  ....................................................
+  ....................................................
+  ........... ...............................done.
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/predeactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/postdeactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/preactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env2/bin/postactivate  New python executable in env2/bin/python
+  (env2)$ ls $WORKON_HOME
+  env1            env2            hook.log
+
+Switch between environments with ``workon``::
+
+  (env2)$ workon env1
+  (env1)$ echo $VIRTUAL_ENV
+  /Users/dhellmann/Envs/env1
+  (env1)$ 
+
+The ``workon`` command also includes tab completion for the
+environment names, and invokes customization scripts as an environment
+is activated or deactivated (see :ref:`scripts`).
+
+::
+
+  (env1)$ echo 'cd $VIRTUAL_ENV' >> $WORKON_HOME/postactivate
+  (env1)$ workon env2
+  (env2)$ pwd
+  /Users/dhellmann/Envs/env2
+
+:ref:`scripts-postmkvirtualenv` is run when a new environment is
+created, letting you automatically install commonly-used tools.
+
+::
+
+  (env2)$ echo 'pip install sphinx' >> $WORKON_HOME/postmkvirtualenv
+  (env3)$ mkvirtualenv env3
+  New python executable in env3/bin/python
+  Installing distribute...............................
+  ....................................................
+  ....................................................
+  ........... ...............................done.
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/predeactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/postdeactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/preactivate
+  virtualenvwrapper.user_scripts Creating /Users/dhellmann/Envs/env3/bin/postactivate
+  Downloading/unpacking sphinx
+    Downloading Sphinx-0.6.5.tar.gz (972Kb): 972Kb downloaded
+    Running setup.py egg_info for package sphinx
+      no previously-included directories found matching 'doc/_build'
+  Downloading/unpacking Pygments>=0.8 (from sphinx)
+    Downloading Pygments-1.3.1.tar.gz (1.1Mb): 1.1Mb downloaded
+    Running setup.py egg_info for package Pygments
+  Downloading/unpacking Jinja2>=2.1 (from sphinx)
+    Downloading Jinja2-2.4.tar.gz (688Kb): 688Kb downloaded
+    Running setup.py egg_info for package Jinja2
+      warning: no previously-included files matching '*' found under directory 'docs/_build/doctrees'
+  Downloading/unpacking docutils>=0.4 (from sphinx)
+    Downloading docutils-0.6.tar.gz (1.4Mb): 1.4Mb downloaded
+    Running setup.py egg_info for package docutils
+  Installing collected packages: docutils, Jinja2, Pygments, sphinx
+    Running setup.py install for docutils
+    Running setup.py install for Jinja2
+    Running setup.py install for Pygments
+    Running setup.py install for sphinx
+      no previously-included directories found matching 'doc/_build'
+      Installing sphinx-build script to /Users/dhellmann/Envs/env3/bin
+      Installing sphinx-quickstart script to /Users/dhellmann/Envs/env3/bin
+      Installing sphinx-autogen script to /Users/dhellmann/Envs/env3/bin
+  Successfully installed docutils Jinja2 Pygments sphinx  (env3)$ 
+  (venv3)$ which sphinx-build
+  /Users/dhellmann/Envs/env3/bin/sphinx-build
+
+Through a combination of the existing functions defined by the core
+package (see :ref:`command`), third-party plugins (see
+:ref:`plugins`), and user-defined scripts (see :ref:`scripts`)
+virtualenvwrapper gives you a wide variety of opportunities to
+automate repetitive operations.
 
 =======
 Details
 .. toctree::
    :maxdepth: 2
 
+   install
    command_ref
    hooks
    tips

docs/source/install.rst

+============
+Installation
+============
+
+WORKON_HOME
+===========
+
+The variable ``WORKON_HOME`` tells virtualenvwrapper where to place
+your virtual environments.  The default is ``$HOME/.virtualenvs``.
+This directory must be created before using any virtualenvwrapper
+commands.
+
+Shell Startup File
+==================
+
+Add two lines to your shell startup file (``.bashrc``, ``.profile``,
+etc.) to set the location where the virtual environments should live
+and the location of the script installed with this package::
+
+    export WORKON_HOME=$HOME/.virtualenvs
+    source /usr/local/bin/virtualenvwrapper.sh
+
+After editing it, reload the startup file (e.g., run: ``source
+~/.bashrc``).
+
+Python Interpreter and $PATH
+============================
+
+During startup, ``virtualenvwrapper.sh`` finds the first ``python`` on
+the ``$PATH`` and remembers it to use later.  This eliminates any
+conflict as the ``$PATH`` changes, enabling interpreters inside
+virtual environments where virtualenvwrapper is not installed.
+Because of this behavior, it is important for the ``$PATH`` to be set
+**before** sourcing ``virtualenvwrapper.sh``.  For example::
+
+    export PATH=/usr/local/bin:$PATH
+    source /usr/local/bin/virtualenvwrapper.sh
+
+To override the ``$PATH`` search, set the variable
+``VIRTUALENVWRAPPER_PYTHON`` to the full path of the interpreter to
+use (also **before** sourcing ``virtualenvwrapper.sh``).  For
+example::
+
+    export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
+    source /usr/local/bin/virtualenvwrapper.sh
+
+Quick-Start
+===========
+
+1. Run: ``workon``
+2. A list of environments, empty, is printed.
+3. Run: ``mkvirtualenv temp``
+4. A new environment, ``temp`` is created and activated.
+5. Run: ``workon``
+6. This time, the ``temp`` environment is included.
+
+Temporary Files
+===============
+
+virtualenvwrapper creates temporary files in ``$TMPDIR``.  If the
+variable is not set, it uses ``/tmp``.  To change the location of
+temporary files just for virtualenvwrapper, set
+``VIRTUALENVWRAPPER_TMPDIR``.
+
+Upgrading from 1.x
+==================
+
+The shell script containing the wrapper functions has been renamed in
+the 2.x series to reflect the fact that shells other than bash are
+supported.  In your startup file, change ``source
+/usr/local/bin/virtualenvwrapper_bashrc`` to ``source
+/usr/local/bin/virtualenvwrapper.sh``.

docs/source/plugins.rst

 Extending Virtualenvwrapper
 ===========================
 
-Customizing one's development environment is a practice adopted from
-other tool-based jobs in which long experience leads to home-grown and
-unique solutions to persistent annoyances.  Carpenters build jigs,
-software developers write shell scripts.  virtualenvwrapper continues
-the tradition of encouraging a craftsman to modify his tools to work
-the way he wants, rather than the other way around.
+Long experience with home-grown solutions for customizing a
+development environment has proven how valuable it can be to have the
+ability to automate common tasks and eliminate persistent annoyances.
+Carpenters build jigs, software developers write shell scripts.
+virtualenvwrapper continues the tradition of encouraging a craftsman
+to modify their tools to work the way they want, rather than the other
+way around.
 
 Use the hooks provided to eliminate repetitive manual operations and
-streamline your development workflow.  For example, the pre_activate
-and post_activate hooks can trigger an IDE to load a project file to
-reload files from the last editing session, manage time-tracking
-records, or start and stop development versions of an application
-server.  The initialize hook can be used to add entirely new commands
-and hooks to virtualenvwrapper.  And the pre_mkvirtualenv and
-post_mkvirtualenv hooks give you an opportunity to install basic
-requirements into each new development environment, initialize a
-source code control repository, or otherwise set up a new project.
+streamline your development workflow.  For example, set up the
+:ref:`plugins-pre_activate` and :ref:`plugins-post_activate` hooks to
+trigger an IDE to load a project file to reload files from the last
+editing session, manage time-tracking records, or start and stop
+development versions of an application server.  Use the
+:ref:`plugins-initialize` hook to add entirely new commands and hooks
+to virtualenvwrapper.  And the :ref:`plugins-pre_mkvirtualenv` and
+:ref:`plugins-post_mkvirtualenv` hooks give you an opportunity to
+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
 
   $ python -m virtualenvwrapper.hook_loader -h
   Usage: virtualenvwrapper.hook_loader [options] <hook> [<arguments>]
-
+  
   Manage hooks for virtualenvwrapper
-
+  
   Options:
-    -h, --help     show this help message and exit
-    -s, --source   Print the shell commands to be run in the current shell
-    -v, --verbose  Show more information on the console
-    -q, --quiet    Show less information on the console
-
+    -h, --help            show this help message and exit
+    -s, --source          Print the shell commands to be run in the current
+                          shell
+    -l, --list            Print a list of the plugins available for the given
+                          hook
+    -v, --verbose         Show more information on the console
+    -q, --quiet           Show less information on the console
+    -n NAMES, --name=NAMES
+                          Only run the hook from the named plugin
+  
 To run the extensions for the initialize hook::
 
   $ python -m virtualenvwrapper.hook_loader -v initialize
 
   $ python -m virtualenvwrapper.hook_loader --source initialize
 
+In practice, rather than invoking the hook loader directly it is more
+convenient to use the shell function, ``virtualenvwrapper_run_hook``
+to run the hooks in both modes.::
+
+  $ virtualenvwrapper_run_hook initialize
+
+All of the arguments given to shell function are passed directly to
+the hook loader.
+
 Logging
 -------
 
 an environment is deleted.  The name of the environment being deleted
 is passed as the first argument.
 
+Adding New Extension Points
+===========================
+
+Plugins that define new operations can also define new extension
+points.  No setup needs to be done to allow the hook loader to find
+the extensions; documenting the names and adding calls to
+``virtualenvwrapper_run_hook`` is sufficient to cause them to be
+invoked.  
+
+The hook loader assumes all extension point names start with
+``virtualenvwrapper.`` and new plugins will want to use their own
+namespace qualifier to append to that.  For example, the project_
+extension defines new events around creating project directories (pre
+and post).  These are called
+``virtualenvwrapper.project.pre_mkproject`` and
+``virtualenvwrapper.project.post_mkproject``.  These are invoked
+with::
+
+  virtualenvwrapper_run_hook project.pre_mkproject $project_name
+
+and::
+
+  virtualenvwrapper_run_hook project.post_mkproject
+
+respectively.
 
 .. _Distribute: http://packages.python.org/distribute/
+
+.. _project: http://www.doughellmann.com/projects/virtualenvwrapper.project/
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.