more doc cleanup

Author: dhellmann

README.rst

@@ -23,6 +23,10 @@ Features
 4.  Tab completion for commands that take a virtual environment as
     argument.
 
+5. User-configurable hooks for all operations.
+
+6. Plugin system for more creating sharable extensions.
+
 Rich Leland has created a short `screencast
 <http://mathematism.com/2009/jul/30/presentation-pip-and-virtualenv/>`__
 showing off the features of virtualenvwrapper.
@@ -34,15 +38,15 @@ Quick Setup
 1. Create a directory to hold all of the virtual environments. The default is
    ``$HOME/.virtualenvs``.
 
-2. Add two lines to your shell startup script (``.bashrc``,
-   ``.bash_profile``, etc.) to set the location where the virtual
+2. 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
 
-3. Run: ``source ~/.bashrc``
+3. Reload the startup file (e.g., run: ``source ~/.bashrc``).
 4. Run: ``workon``
 5. A list of environments, empty, is printed.
 6. Run: ``mkvirtualenv temp``

docs/source/command_ref.rst

@@ -24,8 +24,8 @@ Syntax::
 
 .. seealso::
 
-   * :ref:`hooks-scripts-premkvirtualenv`
-   * :ref:`hooks-scripts-postmkvirtualenv`
+   * :ref:`scripts-premkvirtualenv`
+   * :ref:`scripts-postmkvirtualenv`
 
 rmvirtualenv
 ------------
@@ -38,8 +38,8 @@ Syntax::
 
 .. seealso::
 
-   * :ref:`hooks-scripts-prermvirtualenv`
-   * :ref:`hooks-scripts-postrmvirtualenv`
+   * :ref:`scripts-prermvirtualenv`
+   * :ref:`scripts-postrmvirtualenv`
 
 cpvirtualenv
 ------------
@@ -55,6 +55,10 @@ Syntax::
    The environment created by the copy operation is made `relocatable
    <http://virtualenv.openplans.org/#making-environments-relocatable>`__.
 
+==================================
+Controlling the Active Environment
+==================================
+
 workon
 ------
 
@@ -69,10 +73,10 @@ is printed to stdout.
 
 .. seealso::
 
-   * :ref:`hooks-scripts-predeactivate`
-   * :ref:`hooks-scripts-postdeactivate`
-   * :ref:`hooks-scripts-preactivate`
-   * :ref:`hooks-scripts-postactivate`
+   * :ref:`scripts-predeactivate`
+   * :ref:`scripts-postdeactivate`
+   * :ref:`scripts-preactivate`
+   * :ref:`scripts-postactivate`
 
 deactivate
 ----------
@@ -91,8 +95,8 @@ Syntax::
 
 .. seealso::
 
-   * :ref:`hooks-scripts-predeactivate`
-   * :ref:`hooks-scripts-postdeactivate`
+   * :ref:`scripts-predeactivate`
+   * :ref:`scripts-postdeactivate`
 
 ==================================
 Quickly Navigating to a virtualenv
@@ -104,6 +108,12 @@ currently-active virtualenv.
 cdvirtualenv
 ------------
 
+Change the current working directory to ``$VIRTUAL_ENV``.
+
+Syntax::
+
+    cdvirtualenv [subdir]
+
 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
@@ -124,6 +134,13 @@ subdirectory.
 cdsitepackages
 --------------
 
+Change the current working directory to the ``site-packages`` for
+``$VIRTUAL_ENV``.
+
+Syntax::
+
+    cdsitepackages [subdir]
+
 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
@@ -132,29 +149,28 @@ allowed, to specify a directory hierarchy within the ``site-packages``
 directory to change into.
 
 ::
+
   $ workon pymotw
   $ echo $VIRTUAL_ENV
   /Users/dhellmann/.virtualenvs/pymotw
   $ cdsitepackages PyMOTW/bisect/
   $ pwd
   /Users/dhellmann/.virtualenvs/pymotw/lib/python2.6/site-packages/PyMOTW/bisect
 
+lssitepackages
+--------------
+
+Calling ``lssitepackages`` shows the content of the ``site-packages``
+directory of the currently-active virtualenv.
+
+Syntax::
+
+    lssitepackages
+
 ===============
 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
 --------------
 
@@ -165,17 +181,20 @@ 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.
+Sometimes it is desirable to share installed packages that are not in
+the system ``site-pacakges`` directory and which should not be
+installed in each virtualenv.  One possible solution is to 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.
 
-lssitepackages
---------------
+The directory names are added to a path file named
+``virtualenv_path_extensions.pth`` inside the site-packages directory
+for the environment.
 
-Calling ``lssitepackages`` shows the content of the ``site-packages``
-directory of the currently-active virtualenv.
+*Based on a contribution from James Bennett and Jannis Leidel.*

docs/source/index.rst

@@ -24,7 +24,9 @@ Features
 3. Use a single command to switch between environments.
 4. Tab completion for commands that take a virtual environment as
    argument.
-5. User-configurable hooks for all operations.
+5. User-configurable hooks for all operations (see :ref:`scripts`).
+6. Plugin system for more creating sharable extensions (see
+   :ref:`plugins`).
 
 ===========
 Quick Setup
@@ -33,13 +35,15 @@ Quick Setup
 1. Create a directory to hold all of the virtual environments. The default is
    ``$HOME/.virtualenvs``.
 
-2. 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::
+2. 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
 
-3. Run: ``source ~/.bashrc``
+3. Reload the startup file (e.g., run: ``source ~/.bashrc``).
 4. Run: ``workon``
 5. A list of environments, empty, is printed.
 6. Run: ``mkvirtualenv temp``

docs/source/plugins.rst

@@ -1,4 +1,4 @@
-.. _developers-extensions:
+.. _plugins:
 
 ===================
  Extension Plugins