Commits

Peter Sagerson committed b827a56

Link README and doc/index.rst by include rather than symlink.

Comments (0)

Files changed (2)

-doc/index.rst
+=============
+virtualenv-sh
+=============
+
+This project is my personal substitute for the venerable `virtualenvwrapper
+<http://pypi.python.org/pypi/virtualenvwrapper>`_ (a set of shell functions to
+facilitate the use of `virtualenv <http://pypi.python.org/pypi/virtualenv>`_).
+Like many, I've used virtualenvwrapper for years, but it's gotten a bit heavy
+over time. I eventually found myself waiting too long for new shells to start
+up, even though I tended to use only the basic features.
+
+This project is an attempt to solve that problem. I borrowed the clever bits
+of virtualenvwrapper, discarded everything I considered expensive or just not
+interesting, and added a feature or two of my own. The number one priority of
+this project is speed. The code is almost pure shell script, although there
+may be one or two invocations of standard tools like grep or sed.
+
+Be warned that this implementation may not be for you. I may have gotten rid
+of a feature that you liked, either because it was expensive or because I just
+didn't care about it. I may have accidentally discarded a fix or workaround
+for some environment that I haven't encountered. I may have just introduced
+new bugs (shell is an easy language to get wrong in subtle ways). Proceed at
+your own risk.
+
+
+Installing
+==========
+
+virtualenv-sh can be installed with pip or easy_install. To use it, you need
+to source a single shell script in your shell environment. By default, pip or
+easy_install should install it to /usr/local/bin. If you're using bash or zsh,
+you should import the shell-specific script; otherwise, you can try the
+generic one. Add *one* of the following to your shell's init script (.bashrc,
+.zshrc, etc.)::
+
+    . /usr/local/bin/virtualenv-sh.bash
+
+::
+
+    . /usr/local/bin/virtualenv-sh.zsh
+
+::
+
+    . /usr/local/bin/virtualenv-sh.sh
+
+Nothing else is required. There's only one environment variable that you can
+use for configuration, which is WORKON_HOME. This is a path to your collection
+of virutalenvs; you can leave it blank to accept the default of
+``${HOME}/.virtualenvs``. It is assumed that ``virtualenv`` itself is in your
+path.
+
+::
+
+    WORKON_HOME=${HOME}/.virtualenvs
+
+
+zsh
+---
+
+If you're using zsh, you can instead use the precompiled function archive for
+optimal performance, although this needs to be compiled from source on your
+machine. You can download the source directly or try::
+
+    > pip install --upgrade --no-install virtualenv-sh
+    > cd build/virtualenv-sh
+    > sudo make install
+
+This will find zsh in your path, use it to compile virtualenv-sh.zwc, and
+install it to /usr/local/bin. You can now autoload these functions and
+initialize virtualenv-sh. You may want to refer to the section on function
+autoloading in the zsh manual if you're not familiar with this process::
+
+    # Configure all virtualenv-sh functions for autoloading
+    fpath=(/usr/local/bin/virtualenv-sh $fpath)
+    autoload -w /usr/local/bin/virtualenv-sh
+
+    # Call the main initialization function
+    virtualenv_sh_init
+
+
+Using
+=====
+
+The basic commands of virtualenv-sh are essentially the same as
+virtualenvwrapper. Here's a brief recap:
+
+  ``mkvirtualenv <env_name>``
+
+    Creates a new virtual_env in ``$WORKON_HOME``. All arguments are passed
+    directly to ``virtualenv``. The new virtual_env will become active. Unlike
+    virtualenvwrapper, this takes no additional arguments.
+
+  ``rmvirtualenv <env_name>``
+
+    Deletes an existing virtual_env. If this virtual_env is currently active,
+    it is deactivated first as a courtesy.
+
+  ``workon [<env_name>]``
+
+    Activates the named virtual_env. If another virtual_env is currently
+    active, it will be deactivated first. Without arguments, it will list the
+    available virtual_envs. In compatible shells, you can choose a virtual_env
+    from a menu.
+
+  ``autoworkon``
+
+    Automatically sets the virtual_env based on special files. See below.
+
+  ``deactivate``
+
+    Deactivates the current virtual_env (as when using ``virtualenv``
+    directly).
+
+  ``lsvirtualenvs``
+
+    Prints a list of the virtual_envs you've created.
+
+  ``cdvirtualenv [subdir]``
+
+    Changes the current directory to the root of the active virtual_env, or a
+    subdirectory thereof.
+
+  ``lssitepackages``
+
+    Lists the contents of the active virtual_env's site-packages directory.
+
+  ``cdsitepackages [subdir]``
+
+    Changes the currect directory to the site-packages directory of the active
+    virtual_env, or a subdirectory thereof.
+
+
+Hooks
+=====
+
+virtualenv-sh supports the same global and local (per-env) hooks as
+virtualenvwrapper. Global hooks are files in $WORKON_HOME; local hooks are
+files in $WORKON_HOME/\{virtual_env\}/bin. Hooks are executed by sourcing them
+in the current shell context.
+
+  initialize (global)
+
+    Called at the end of virtualenv_sh_init.
+
+  premkvirtualenv, postmkvirtualv, prermvirtualenv, postmkvirtualenv (global)
+
+    Called at the beginning and end of mkvirtualenv and rmvirtualenv.
+
+  preactivate, postactivate (global, local); predeactivate, postdeactivate (local, global)
+
+    Called in the order indicated around activation and deactivation of a
+    virtual_env.
+
+In addition, virtualenv-sh allows you to dynamically register functions to be
+called when executing hooks::
+
+    virtualenv_sh_add_hook <hook_name> <function_name>
+    virtualenv_sh_remove_hook <hook_name> <function_name>
+
+e.g.::
+
+    my_virtualenv_cleanup()
+    {
+        # Do some stuff here
+    }
+
+    virtualenv_sh_add_hook postdeactivate my_virtualenv_cleanup
+
+Registered hook functions are always executed after all global and local hook
+scripts.
+
+
+autoworkon
+==========
+
+autoworkon is a new command that is designed to automatically update your
+virtual_env based on your current directory. Note that there is no standard
+shell mechanism for running a function when the current directory changes--and
+many shells don't have such a mechanism--so installing this is up to you. If
+you're using zsh, you would use::
+
+    autoload -U add-zsh-hook
+    add-zsh-hook chpwd autoworkon
+
+The autoworkon function will walk up the filesystem from the current directory
+until it either reaches the root or finds an item named ".workon". If this is
+a readable file, it will treat the first line as the name of a virtual_env and
+activate it. There are a few special rules to keep in mind:
+
+  * autoworkon always stops at the first .workon it finds. It's perfectly
+    reasonable to have .workon files at multiple points in a directory tree to
+    use different virtual_envs at different levels.
+
+  * An empty or unreadable .workon file is interpreted as "no virtual_env".
+    This is useful if you want to deactivate the automatic virtual_env in a
+    particular subtree.
+
+  * If you activate a virtual_env manually, autoworkon will never override it.
+    autoworkon will only change your active virtual_env if it is unset or was
+    previously set by autoworkon.
-=============
-virtualenv-sh
-=============
-
-This project is my personal substitute for the venerable `virtualenvwrapper
-<http://pypi.python.org/pypi/virtualenvwrapper>`_ (a set of shell functions to
-facilitate the use of `virtualenv <http://pypi.python.org/pypi/virtualenv>`_).
-Like many, I've used virtualenvwrapper for years, but it's gotten a bit heavy
-over time. I eventually found myself waiting too long for new shells to start
-up, even though I tended to use only the basic features.
-
-This project is an attempt to solve that problem. I borrowed the clever bits
-of virtualenvwrapper, discarded everything I considered expensive or just not
-interesting, and added a feature or two of my own. The number one priority of
-this project is speed. The code is almost pure shell script, although there
-may be one or two invocations of standard tools like grep or sed.
-
-Be warned that this implementation may not be for you. I may have gotten rid
-of a feature that you liked, either because it was expensive or because I just
-didn't care about it. I may have accidentally discarded a fix or workaround
-for some environment that I haven't encountered. I may have just introduced
-new bugs (shell is an easy language to get wrong in subtle ways). Proceed at
-your own risk.
-
-
-Installing
-==========
-
-virtualenv-sh can be installed with pip or easy_install. To use it, you need
-to source a single shell script in your shell environment. By default, pip or
-easy_install should install it to /usr/local/bin. If you're using bash or zsh,
-you should import the shell-specific script; otherwise, you can try the
-generic one. Add *one* of the following to your shell's init script (.bashrc,
-.zshrc, etc.)::
-
-    . /usr/local/bin/virtualenv-sh.bash
-
-::
-
-    . /usr/local/bin/virtualenv-sh.zsh
-
-::
-
-    . /usr/local/bin/virtualenv-sh.sh
-
-Nothing else is required. There's only one environment variable that you can
-use for configuration, which is WORKON_HOME. This is a path to your collection
-of virutalenvs; you can leave it blank to accept the default of
-``${HOME}/.virtualenvs``. It is assumed that ``virtualenv`` itself is in your
-path.
-
-::
-
-    WORKON_HOME=${HOME}/.virtualenvs
-
-
-zsh
----
-
-If you're using zsh, you can instead use the precompiled function archive for
-optimal performance, although this needs to be compiled from source on your
-machine. You can download the source directly or try::
-
-    > pip install --upgrade --no-install virtualenv-sh
-    > cd build/virtualenv-sh
-    > sudo make install
-
-This will find zsh in your path, use it to compile virtualenv-sh.zwc, and
-install it to /usr/local/bin. You can now autoload these functions and
-initialize virtualenv-sh. You may want to refer to the section on function
-autoloading in the zsh manual if you're not familiar with this process::
-
-    # Configure all virtualenv-sh functions for autoloading
-    fpath=(/usr/local/bin/virtualenv-sh $fpath)
-    autoload -w /usr/local/bin/virtualenv-sh
-
-    # Call the main initialization function
-    virtualenv_sh_init
-
-
-Using
-=====
-
-The basic commands of virtualenv-sh are essentially the same as
-virtualenvwrapper. Here's a brief recap:
-
-  ``mkvirtualenv <env_name>``
-
-    Creates a new virtual_env in ``$WORKON_HOME``. All arguments are passed
-    directly to ``virtualenv``. The new virtual_env will become active. Unlike
-    virtualenvwrapper, this takes no additional arguments.
-
-  ``rmvirtualenv <env_name>``
-
-    Deletes an existing virtual_env. If this virtual_env is currently active,
-    it is deactivated first as a courtesy.
-
-  ``workon [<env_name>]``
-
-    Activates the named virtual_env. If another virtual_env is currently
-    active, it will be deactivated first. Without arguments, it will list the
-    available virtual_envs. In compatible shells, you can choose a virtual_env
-    from a menu.
-
-  ``autoworkon``
-
-    Automatically sets the virtual_env based on special files. See below.
-
-  ``deactivate``
-
-    Deactivates the current virtual_env (as when using ``virtualenv``
-    directly).
-
-  ``lsvirtualenvs``
-
-    Prints a list of the virtual_envs you've created.
-
-  ``cdvirtualenv [subdir]``
-
-    Changes the current directory to the root of the active virtual_env, or a
-    subdirectory thereof.
-
-  ``lssitepackages``
-
-    Lists the contents of the active virtual_env's site-packages directory.
-
-  ``cdsitepackages [subdir]``
-
-    Changes the currect directory to the site-packages directory of the active
-    virtual_env, or a subdirectory thereof.
-
-
-Hooks
-=====
-
-virtualenv-sh supports the same global and local (per-env) hooks as
-virtualenvwrapper. Global hooks are files in $WORKON_HOME; local hooks are
-files in $WORKON_HOME/\{virtual_env\}/bin. Hooks are executed by sourcing them
-in the current shell context.
-
-  initialize (global)
-
-    Called at the end of virtualenv_sh_init.
-
-  premkvirtualenv, postmkvirtualv, prermvirtualenv, postmkvirtualenv (global)
-
-    Called at the beginning and end of mkvirtualenv and rmvirtualenv.
-
-  preactivate, postactivate (global, local); predeactivate, postdeactivate (local, global)
-
-    Called in the order indicated around activation and deactivation of a
-    virtual_env.
-
-In addition, virtualenv-sh allows you to dynamically register functions to be
-called when executing hooks::
-
-    virtualenv_sh_add_hook <hook_name> <function_name>
-    virtualenv_sh_remove_hook <hook_name> <function_name>
-
-e.g.::
-
-    my_virtualenv_cleanup()
-    {
-        # Do some stuff here
-    }
-
-    virtualenv_sh_add_hook postdeactivate my_virtualenv_cleanup
-
-Registered hook functions are always executed after all global and local hook
-scripts.
-
-
-autoworkon
-==========
-
-autoworkon is a new command that is designed to automatically update your
-virtual_env based on your current directory. Note that there is no standard
-shell mechanism for running a function when the current directory changes--and
-many shells don't have such a mechanism--so installing this is up to you. If
-you're using zsh, you would use::
-
-    autoload -U add-zsh-hook
-    add-zsh-hook chpwd autoworkon
-
-The autoworkon function will walk up the filesystem from the current directory
-until it either reaches the root or finds an item named ".workon". If this is
-a readable file, it will treat the first line as the name of a virtual_env and
-activate it. There are a few special rules to keep in mind:
-
-  * autoworkon always stops at the first .workon it finds. It's perfectly
-    reasonable to have .workon files at multiple points in a directory tree to
-    use different virtual_envs at different levels.
-
-  * An empty or unreadable .workon file is interpreted as "no virtual_env".
-    This is useful if you want to deactivate the automatic virtual_env in a
-    particular subtree.
-
-  * If you activate a virtual_env manually, autoworkon will never override it.
-    autoworkon will only change your active virtual_env if it is unset or was
-    previously set by autoworkon.
+.. include:: ../README