Commits

Doug Hellmann committed 8dfb27d

clean up and update docs, reduce size of readme, start working on packaging changes

Comments (0)

Files changed (8)

 include pavement.py
 include tests/*
 recursive-include docs *.html *.txt *.css *.js *.png
-recursive-include docsource *.rst *.txt *.py
+recursive-include docsource *.rst
 virtualenvwrapper
 #################
 
+virtualenvwrapper is a set of extensions to Ian Bicking's `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ tool.  The extensions include wrappers for creating and deleting virtual environments and otherwise managing your development workflow, making it easier to work on more than one project at a time without introducing conflicts in their dependencies.
+
 ===========
 Quick Setup
 ===========
 7. Run: ``workon``
 8. This time, the ``temp`` environment is included.
 
-
-===============
-Path Management
-===============
-
-Sometimes it is desirable to share installed packages that are not in the system ``site-pacakges`` directory and which you do not want to install in each virtualenv.  In this case, you *could* symlink the source into the environment ``site-packages`` directory, but it is also easy to add extra directories to the PYTHONPATH by including them in a .pth file inside ``site-packages`` using ``add2virtualenv``.
-
-1. Check out the source for a big project, such as Django.
-2. Run: ``add2virtualenv path_to_source``.
-3. Run: ``add2virtualenv``.
-4. A usage message and list of current "extra" paths is printed.
-
-============
-Hook Scripts
-============
-
-virtualenvwrapper adds several hook points you can use to change your settings 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.
-
-$VIRTUAL_ENV/bin/postactivate
-=============================
-
-The ``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
-
-$VIRTUAL_ENV/bin/predeactivate
-==============================
-
-The ``predeactivate`` script is source 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.
-
-$WORKON_HOME/postactivate
-=============================
-
-The global ``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"
-
-$WORKON_HOME/premkvirtualenv
-=============================
-
-The ``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.
-
-$WORKON_HOME/postmkvirtualenv
-=============================
-
-The ``postmkvirtualenv`` script is sourced after the new environment is created and
-activated.
-
-$WORKON_HOME/prermvirtualenv
-============================
-
-The ``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.
-
-$WORKON_HOME/postrmvirtualenv
-=============================
-
-The ``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.
-
-===============
-Path Management
-===============
-
-The function ``add2virtualenv`` adds the specified directories to the Python path for the
-active virtualenv. The directory names passed as argument are added to a path file named
-``virtualenv_path_extensions.pth`` inside the virtualenv's site-packages directory. If this
-file does not exist, it will be created first.
-
-==================================
-Quickly Navigating to a virtualenv
-==================================
-
-There are two functions to provide shortcuts to navigate into the the currently-active
-virtualenv.
-
-cdvirtualenv
-============
-
-Calling ``cdvirtualenv`` changes the current working directory to the top of the virtualenv (``$VIRTUAL_ENV``).  An optional argument is appended to the path, allowing navigation directly into a subdirectory.
-
-::
-
-  $ workon pymotw
-  $ echo $VIRTUAL_ENV
-  /Users/dhellmann/.virtualenvs/pymotw
-  $ cdvirtualenv
-  $ pwd
-  /Users/dhellmann/.virtualenvs/pymotw
-  $ cdvirtualenv bin
-  $ pwd
-  /Users/dhellmann/.virtualenvs/pymotw/bin
-
-cdsitepackages
-==============
-
-Because the exact path to the site-packages directory in the virtualenv depends on the
-version of Python, ``cdsitepackages`` is provided as a shortcut for ``cdvirtualenv
-lib/python${pyvers}/site-packages``.
-
 ==========
 References
 ==========
 <http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html>`_.
 
 =======
-Updates
-=======
-
-1.16
-
-  - Merged in changes to ``cdvirtualenv`` from wam and added tests and docs.
-  - Merged in changes to make error messages go to stderr, also provided by wam.
-
-1.15
-  - Better error handling in mkvirtualenv.
-  - Remove bogus VIRTUALENV_WRAPPER_BIN variable.
-
-1.14
-  - Wrap the virtualenv version of deactivate() with one that lets us invoke
-    the predeactivate hooks.
-  - Fix virtualenvwrapper_show_workon_options for colorized versions of ls and
-    write myself a note so I don't break it again later.
-  - Convert test.sh to use true tests with `shunit2 <http://shunit2.googlecode.com/>`_
-
-1.13
-  - Fix issue #5 by correctly handling symlinks and limiting the list of envs to things 
-    that look like they can be activated.
-
-1.12
-  - Check return value of virtualenvwrapper_verify_workon_home everywhere, thanks to 
-    Jeff Forcier for pointing out the errors.
-  - Fix instructions at top of README, pointed out by Matthew Scott.
-  - Add cdvirtualenv and cdsitepackages, contributed by James Bennett.
-  - Enhance test.sh.
-
-1.11
-  - Optimize virtualenvwrapper_show_workon_options.
-  - Add global postactivate hook.
-
-1.10
-  - Pull in fix for colorized ls from Jeff Forcier (b42a25f7b74a).
-
-1.9
-  - Add more hooks for operations to run before and after creating or deleting environments based on changes from Chris Hasenpflug.
-
-1.8.1
-  - Corrected a problem with change to mkvirtualenv that lead to release 1.8 by using an alternate fix proposed by James in comments on release 1.4.
-
-1.8
-  - Fix for processing the argument list in mkvirtualenv from jorgevargas (BitBucket issue #1)
-
-1.7
-  - Move to bitbucket.org for hosting
-  - clean up TODO list and svn keywords
-  - add license section below
-
-1.6.1
-
-  - More zsh support (fixes to rmvirtualenv) from Byron Clark.
-
-1.6
-
-  - Add completion support for zsh, courtesy of Ted Leung.
-
-1.5
-
-  - Fix some issues with spaces in directory or env names.  They still don't really work with virtualenv, though.
-  - Added documentation for the postactivate and predeactivate scripts.
-
-1.4
-
-  - Includes a new .pth management function based on work contributed by James Bennett and Jannis Leidel.
-
-1.3.x
-
-  - Includes a fix for a nasty bug in rmvirtualenv identified by John Shimek.
-
-=======
 License
 =======
 

docsource/command_ref.rst

 .. Quick reference documentation for virtualenvwrapper command line functions
-    Created Thursday, May 28, 2009 by Steve Steiner (ssteinerX@gmail.com)
+    Originally contributed Thursday, May 28, 2009 by Steve Steiner (ssteinerX@gmail.com)
 
-==================
+#################
 Command Reference
-==================
+#################
 
 All of the commands below are to be used on the Terminal command line.
 
-add2virtualenv
---------------
-
-add2virtualenv directory1 directory2 ...
-
-Path management for packages outside of the virtual env.
-Based on a contribution from James Bennett and Jannis Leidel.
-
-
-Adds the specified directories to the Python path for the currently-active
-virtualenv.
-
-This will be done by placing the directory names in a path file
-named "virtualenv_path_extensions.pth" inside the virtualenv's site-packages
-directory; if this file does not exist, it will be created first.
+=====================
+Managing Environments
+=====================
 
 mkvirtualenv
 ------------
 
 Create a new environment, in the WORKON_HOME.
 
-Usage: mkvirtualenv [options] ENVNAME
+Syntax::
+
+    mkvirtualenv [options] ENVNAME
 
 (where the options are passed directly to virtualenv)
 
 rmvirtualenv
 ------------
+
 Remove an environment, in the WORKON_HOME.
 
-Usage: rmvirtualenv ENVNAME
+Syntax::
+
+    rmvirtualenv ENVNAME
 
 workon
-# List or change working virtual environments
-#
-# Usage: workon [environment_name]
-#
+------
+
+List or change working virtual environments
+
+Syntax::
+
+    workon [environment_name]
+
+If no ``environment_name`` is given the list of available environments is printed to stdout.
+
+==================================
+Quickly Navigating to a virtualenv
+==================================
+
+There are two functions to provide shortcuts to navigate into the the currently-active
+virtualenv.
+
+cdvirtualenv
+------------
+
+Calling ``cdvirtualenv`` changes the current working directory to the top of the virtualenv (``$VIRTUAL_ENV``).  An optional argument is appended to the path, allowing navigation directly into a subdirectory.
+
+::
+
+  $ workon pymotw
+  $ echo $VIRTUAL_ENV
+  /Users/dhellmann/.virtualenvs/pymotw
+  $ cdvirtualenv
+  $ pwd
+  /Users/dhellmann/.virtualenvs/pymotw
+  $ cdvirtualenv bin
+  $ pwd
+  /Users/dhellmann/.virtualenvs/pymotw/bin
+
+cdsitepackages
+--------------
+
+Because the exact path to the site-packages directory in the virtualenv depends on the
+version of Python, ``cdsitepackages`` is provided as a shortcut for ``cdvirtualenv
+lib/python${pyvers}/site-packages``.
+
+===============
+Path Management
+===============
+
+Sometimes it is desirable to share installed packages that are not in the system ``site-pacakges`` directory and which you do not want to install in each virtualenv.  In this case, you *could* symlink the source into the environment ``site-packages`` directory, but it is also easy to add extra directories to the PYTHONPATH by including them in a .pth file inside ``site-packages`` using ``add2virtualenv``.
+
+1. Check out the source for a big project, such as Django.
+2. Run: ``add2virtualenv path_to_source``.
+3. Run: ``add2virtualenv``.
+4. A usage message and list of current "extra" paths is printed.
+
+add2virtualenv
+--------------
+
+Adds the specified directories to the Python path for the currently-active
+virtualenv.
+
+Syntax::
+
+    add2virtualenv directory1 directory2 ...
+
+Path management for packages outside of the virtual env.
+Based on a contribution from James Bennett and Jannis Leidel.
+
+This will be done by placing the directory names in a path file
+named ``virtualenv_path_extensions.pth`` inside the virtualenv's site-packages
+directory; if this file does not exist, it will be created first.

docsource/conf.py

 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_use_modindex = True
+html_use_modindex = False
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False

docsource/history.rst

+===============
+Release History
+===============
+
+1.16
+
+  - Merged in changes to ``cdvirtualenv`` from wam and added tests and docs.
+  - Merged in changes to make error messages go to stderr, also provided by wam.
+
+1.15
+  - Better error handling in mkvirtualenv.
+  - Remove bogus VIRTUALENV_WRAPPER_BIN variable.
+
+1.14
+  - Wrap the virtualenv version of deactivate() with one that lets us invoke
+    the predeactivate hooks.
+  - Fix virtualenvwrapper_show_workon_options for colorized versions of ls and
+    write myself a note so I don't break it again later.
+  - Convert test.sh to use true tests with `shunit2 <http://shunit2.googlecode.com/>`_
+
+1.13
+  - Fix issue #5 by correctly handling symlinks and limiting the list of envs to things 
+    that look like they can be activated.
+
+1.12
+  - Check return value of virtualenvwrapper_verify_workon_home everywhere, thanks to 
+    Jeff Forcier for pointing out the errors.
+  - Fix instructions at top of README, pointed out by Matthew Scott.
+  - Add cdvirtualenv and cdsitepackages, contributed by James Bennett.
+  - Enhance test.sh.
+
+1.11
+  - Optimize virtualenvwrapper_show_workon_options.
+  - Add global postactivate hook.
+
+1.10
+  - Pull in fix for colorized ls from Jeff Forcier (b42a25f7b74a).
+
+1.9
+  - Add more hooks for operations to run before and after creating or deleting environments based on changes from Chris Hasenpflug.
+
+1.8.1
+  - Corrected a problem with change to mkvirtualenv that lead to release 1.8 by using an alternate fix proposed by James in comments on release 1.4.
+
+1.8
+  - Fix for processing the argument list in mkvirtualenv from jorgevargas (BitBucket issue #1)
+
+1.7
+  - Move to bitbucket.org for hosting
+  - clean up TODO list and svn keywords
+  - add license section below
+
+1.6.1
+
+  - More zsh support (fixes to rmvirtualenv) from Byron Clark.
+
+1.6
+
+  - Add completion support for zsh, courtesy of Ted Leung.
+
+1.5
+
+  - Fix some issues with spaces in directory or env names.  They still don't really work with virtualenv, though.
+  - Added documentation for the postactivate and predeactivate scripts.
+
+1.4
+
+  - Includes a new .pth management function based on work contributed by James Bennett and Jannis Leidel.
+
+1.3.x
+
+  - Includes a fix for a nasty bug in rmvirtualenv identified by John Shimek.

docsource/hooks.rst

+============
+Hook Scripts
+============
+
+virtualenvwrapper adds several hook points you can use to change your settings 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.
+
+$VIRTUAL_ENV/bin/postactivate
+=============================
+
+The ``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
+
+$VIRTUAL_ENV/bin/predeactivate
+==============================
+
+The ``predeactivate`` script is source 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.
+
+$WORKON_HOME/postactivate
+=============================
+
+The global ``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"
+
+$WORKON_HOME/premkvirtualenv
+=============================
+
+The ``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.
+
+$WORKON_HOME/postmkvirtualenv
+=============================
+
+The ``postmkvirtualenv`` script is sourced after the new environment is created and
+activated.
+
+$WORKON_HOME/prermvirtualenv
+============================
+
+The ``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.
+
+$WORKON_HOME/postrmvirtualenv
+=============================
+
+The ``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.

docsource/index.rst

    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to virtualenvwrapper's documentation!
-=============================================
+#################
+virtualenvwrapper
+#################
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   command_ref
+virtualenvwrapper is a set of extensions to Ian Bicking's `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ tool.  The extensions include wrappers for creating and deleting virtual environments and otherwise managing your development workflow, making it easier to work on more than one project at a time without introducing conflicts in their dependencies.
 
 ===========
 Quick Setup
 ===========
 
-1.  Add a line like ``export WORKON_HOME=$HOME/.virtualenvs`` to your .bashrc.
-
-2.  Add a line like ``source /path/to/this/file/virtualenvwrapper_bashrc``
-    to your .bashrc.
-
-3.  Run: ``source ~/.bashrc``
-
-4.  Run: ``workon``
-
-5.  A list of environments, empty, is printed.
-
-6.  Run: ``mkvirtualenv temp``
-
-7.  Run: ``workon``
-
-8.  A new environment, ``temp`` is created and activated.
-
-9.  This time, the ``temp`` environment is included.
-
-
-===============
-Path Management
-===============
-
-Sometimes it is desirable to share installed packages that are not in the
-system ``site-pacakges`` directory and which you do not want to install in
-each virtualenv. In this case, you *could* symlink the source into the
-environment ``site-packages`` directory, but it is also easy to add extra
-directories to the PYTHONPATH by including them in a .pth file inside
-``site-packages`` using ``add2virtualenv``.
-
-1. Check out the source for a big project, such as Django.
-2. Run: ``add2virtualenv path_to_source``.
-3. Run: ``add2virtualenv``.
-4. A usage message and list of current "extra" paths is printed.
-
-==================
-Activation Scripts
-==================
-
-virtualenvwrapper adds two separate hook scripts you can use to change your
-settings when moving between environments. They are *sourced* by ``workon`` at
-the appropriate trigger time, allowing them to modify your shell environment.
-
-Both scripts are bash shell scripts and need to be saved in
-``$VIRTUAL_ENV/bin/``.
-
-postactivate
-============
+1. Add two lines to your .bashrc to set the location where the virtual environments should live and the location of the script installed with this package::
 
-The ``postactivate`` script is run after the new environment is enabled.
-``$VIRTUAL_ENV`` refers to the new environment at the time the script runs.
+    export WORKON_HOME=$HOME/.virtualenvs
+    source /usr/local/bin/virtualenvwrapper_bashrc
 
-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.
+2. Run: ``source ~/.bashrc``
+3. Run: ``workon``
+4. A list of environments, empty, is printed.
+5. Run: ``mkvirtualenv temp``
+6. A new environment, ``temp`` is created and activated.
+7. Run: ``workon``
+8. This time, the ``temp`` environment is included.
 
-::
-
-	pymotw_root=/Users/dhellmann/Documents/PyMOTW
-	cd $pymotw_root
-	PATH=$pymotw_root/bin:$PATH
-
-predeactivate
-=============
-
-The ``predeactivate`` script is run 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.
+=======
+Details
+=======
 
-===============
-Path Management
-===============
+.. toctree::
+   :maxdepth: 2
 
-The function ``add2virtualenv`` adds the specified directories to the Python
-path for the active virtualenv. The directory names passed as argument are
-added to a path file named ``virtualenv_path_extensions.pth`` inside the
-virtualenv's site-packages directory. If this file does not exist, it will be
-created first.
+   command_ref
+   hooks
+   history
 
 ==========
 References
 ==========
 
+`virtualenv <http://pypi.python.org/pypi/virtualenv>`_, from Ian Bicking, is a pre-requisite to using these extensions.
+
 For more details, refer to the column I wrote for the May 2008 issue of Python
 Magazine: `virtualenvwrapper | And Now For Something Completely Different
 <http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html>`_.
 
 =======
-Updates
-=======
-
-1.7
-  - Move to bitbucket.org for hosting
-  - clean up TODO list and svn keywords
-  - add license section below
-
-1.6.1
-  - More zsh support (fixes to rmvirtualenv) from Byron Clark.
-
-1.6
-  - Add completion support for zsh, courtesy of Ted Leung.
-
-1.5
-  - Fix some issues with spaces in directory or env names. They still don't
-    really work with virtualenv, though.
-  - Added documentation for the postactivate and predeactivate scripts.
-
-1.4
-  - Includes a new .pth management function based on work contributed by James
-    Bennett and Jannis Leidel.
-
-1.3.x
-  - Includes a fix for a nasty bug in rmvirtualenv identified by John Shimek.
-
-=======
 License
 =======
 
 OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
 CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
 
 # What project are we building?
 PROJECT = 'virtualenvwrapper'
-VERSION = '1.16'
+VERSION = '1.17'
 os.environ['VERSION'] = VERSION
 
 # Read the long description to give to setup
     
     sdist = Bunch(
         dist_dir=os.path.expanduser('~/Desktop'),
-        # Tell Paver to include extra parts that we use
-        # but it doesn't ship in the minilib by default.
+    ),
+
+    # Tell Paver to include extra parts that we use
+    # but it doesn't ship in the minilib by default.
+    minilib = Bunch(
         extra_files=['doctools'],
     ),
     
     return
 
 @task
-@needs(['html', 'generate_setup', 'minilib', 
+@needs(['html', 'readme_html', 'generate_setup', 'minilib', 
         'setuptools.command.sdist'
         ])
 def sdist():
     """
     pass
 
-# @task
-# def html():
-#     # FIXME - Switch to sphinx?
-#     outfile = path('README.html')
-#     outfile.unlink()
-#     sh('rst2html.py %s README.html' % README_FILE)
-#     return
+@task
+def readme_html():
+    # FIXME - Switch to sphinx?
+    outfile = path('README.html')
+    outfile.unlink()
+    sh('rst2html.py %s README.html' % README_FILE)
+    return
 
 @task
 def test():
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.