minor doc updates and formatting changes

dhellmann · dhellmann · commit 8bb2541f247c · 2010-04-03T07:45:23.000-04:00
diff --git a/docs/source/command_ref.rst b/docs/source/command_ref.rst
@@ -20,7 +20,7 @@ Syntax::
 
     mkvirtualenv [options] ENVNAME
 
-(where the options are passed directly to virtualenv)
+(any options are passed directly to ``virtualenv``)
 
 rmvirtualenv
 ------------
@@ -54,32 +54,38 @@ Syntax::
 
     workon [environment_name]
 
-If no ``environment_name`` is given the list of available environments is printed to stdout.
+If no ``environment_name`` is given the list of available environments
+is printed to stdout.
 
 deactivate
 ----------
 
-Switch from a virtual environment to the system-installed version of Python.
+Switch from a virtual environment to the system-installed version of
+Python.
 
 Syntax::
 
     deactivate
 
 .. note::
 
-    This command is actually part of virtualenv, but is wrapped to provide before and after hooks, just as workon does for activate.
+    This command is actually part of virtualenv, but is wrapped to
+    provide before and after hooks, just as workon does for activate.
 
 ==================================
 Quickly Navigating to a virtualenv
 ==================================
 
-There are two functions to provide shortcuts to navigate into the the currently-active
-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.
+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.
 
 ::
 
@@ -96,10 +102,12 @@ Calling ``cdvirtualenv`` changes the current working directory to the top of the
 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``. An optional argument is also allowed, to specify 
-a directory hierarchy within the ``site-packages`` directory to change into.
+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``. An optional argument is also
+allowed, to specify a directory hierarchy within the ``site-packages``
+directory to change into.
 
 ::
   $ workon pymotw
@@ -113,7 +121,12 @@ a directory hierarchy within the ``site-packages`` directory to change into.
 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``.
+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``.
@@ -123,22 +136,24 @@ Sometimes it is desirable to share installed packages that are not in the system
 add2virtualenv
 --------------
 
-Adds the specified directories to the Python path for the currently-active
-virtualenv.
+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.
+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.
+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.
 
 
 lssitepackages
 --------------
 
-Calling ``lssitepackages`` shows the content of the ``site-packages`` directory of the currently-active virtualenv.
+Calling ``lssitepackages`` shows the content of the ``site-packages``
+directory of the currently-active virtualenv.
diff --git a/docs/source/developers.rst b/docs/source/developers.rst
@@ -18,127 +18,48 @@ Paver.  You will need the following packages in order to build the
 docs:
 
 - Sphinx
-- Paver
 - docutils
-- sphinxcontrib-paverutils
 
-Once all of them are installed into a virtualenv using easy_install,
-run ``paver html`` to generate the HTML version of the documentation::
+Once all of the tools are installed into a virtualenv using
+pip, run ``make html`` to generate the HTML version of the
+documentation::
 
-    $ paver html
-    ---> pavement.html
-    ---> sphinxcontrib.paverutils.html
-    mkdir ./docs/html (mode 511)
-    sphinx-build  -b html -d ./docs/doctrees -c sphinx/pkg -Aproject=virtualenvwrapper ./docsource ./docs/html
-    Running Sphinx v0.6.1
+    $ make html
+    rm -rf virtualenvwrapper/docs
+    (cd docs && make html SPHINXOPTS="-c sphinx/pkg")
+    sphinx-build -b html -d build/doctrees  -c sphinx/pkg source build/html
+    Running Sphinx v0.6.4
     loading pickled environment... done
-    building [html]: targets for 4 source files that are out of date
-    updating environment: 1 added, 1 changed, 0 removed
-    reading sources... [ 50%] developers
-    reading sources... [100%] index
-
-    /Users/dhellmann/Devel/virtualenvwrapper/src/docsource/developers.rst:19: (WARNING/2) Literal block expected; none found.
+    building [html]: targets for 2 source files that are out of date
+    updating environment: 0 added, 2 changed, 0 removed
+    reading sources... [ 50%] command_ref
+    reading sources... [100%] developers
+    
     looking for now-outdated files... none found
     pickling environment... done
     checking consistency... done
     preparing documents... done
-    writing output... [ 20%] command_ref
-    writing output... [ 40%] developers
-    writing output... [ 60%] history
-    writing output... [ 80%] hooks
+    writing output... [ 33%] command_ref
+    writing output... [ 66%] developers
     writing output... [100%] index
-
+    
     writing additional files... search
-    copying static files... WARNING: static directory '/Users/dhellmann/Devel/virtualenvwrapper/src/sphinx/pkg/static' does not exist
+    copying static files... WARNING: static directory '/Users/dhellmann/Devel/virtualenvwrapper/plugins/docs/sphinx/pkg/static' does not exist
     done
     dumping search index... done
     dumping object inventory... done
-    build succeeded, 2 warnings.
-    rmtree virtualenvwrapper/docs () {}
-    move docs/html virtualenvwrapper/docs
-
+    build succeeded, 1 warning.
+    
+    Build finished. The HTML pages are in build/html.
+    cp -r docs/build/html virtualenvwrapper/docs
+    
 The output version of the documentation ends up in
 ``./virtualenvwrapper/docs`` inside your sandbox.
 
 Running Tests
 =============
 
 The test suite for virtualenvwrapper uses `shunit2
-<http://shunit2.googlecode.com/>`_.  To run the tests under both bash
-and zsh, use ``paver test``.  To add new tests, modify the
-``tests/test.sh`` script with new test functions.
-
-::
-
-    $ paver test
-    ---> pavement.test
-    bash ./tests/test.sh
-
-    test_mkvirtualenv
-    New python executable in env1/bin/python
-    Installing setuptools............done.
-
-    test_cdvirtual
-
-    test_cdsitepackages
-
-    test_mkvirtualenv_activates
-    New python executable in env2/bin/python
-    Installing setuptools............done.
-
-    test_workon
-
-    test_postactivate_hook
-
-    test_deactivate
-
-    test_deactivate_hooks
-
-    test_virtualenvwrapper_show_workon_options
-
-    test_rmvirtualenv
-    New python executable in deleteme/bin/python
-    Installing setuptools............done.
-
-    test_rmvirtualenv_no_such_env
-
-    test_missing_workon_home
-
-    Ran 12 tests.
-
-    OK
-    SHUNIT_PARENT=./tests/test.sh zsh -o shwordsplit ./tests/test.sh
-
-    test_mkvirtualenv
-    New python executable in env1/bin/python
-    Installing setuptools............done.
-
-    test_cdvirtual
-
-    test_cdsitepackages
-
-    test_mkvirtualenv_activates
-    New python executable in env2/bin/python
-    Installing setuptools............done.
-
-    test_workon
-
-    test_postactivate_hook
-
-    test_deactivate
-
-    test_deactivate_hooks
-
-    test_virtualenvwrapper_show_workon_options
-
-    test_rmvirtualenv
-    New python executable in deleteme/bin/python
-    Installing setuptools............done.
-
-    test_rmvirtualenv_no_such_env
-
-    test_missing_workon_home
-
-    Ran 12 tests.
-
-    OK
+<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.
diff --git a/docs/source/hooks.rst b/docs/source/hooks.rst
@@ -2,17 +2,25 @@
 Hook Scripts
 ============
 
-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.
+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.
 
 Environment Hooks
 =================
 
 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.
+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.
+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.
 
 ::
 
@@ -23,17 +31,24 @@ This example script for the PyMOTW environment changes the current working direc
 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.
+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.
+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``.
+This example script adds a space between the virtual environment name
+and your old PS1 by making use of ``_OLD_VIRTUAL_PS1``.
 
 ::
 
@@ -42,19 +57,28 @@ This example script adds a space between the virtual environment name and your o
 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.
+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.
+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.
+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.
+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.
