Refactor the venv API docs into a real API doc style.

Doc/library/venv.rst

@@ -15,28 +15,26 @@
 
 --------------
 
-The :mod:`venv` module provides support for creating lightweight
-"virtual environments" with their own site directories, optionally
-isolated from system site directories.  Each virtual environment has
-its own Python binary (allowing creation of environments with various
-Python versions) and can have its own independent set of installed
-Python packages in its site directories.
+The :mod:`venv` module provides support for creating lightweight "virtual
+environments" with their own site directories, optionally isolated from system
+site directories.  Each virtual environment has its own Python binary (allowing
+creation of environments with various Python versions) and can have its own
+independent set of installed Python packages in its site directories.
+
 
 Creating virtual environments
 -----------------------------
 
-Creation of virtual environments is simplest executing the ``pyvenv``
-script::
+Creation of virtual environments is simplest executing the ``pyvenv`` script::
 
     pyvenv /path/to/new/virtual/environment
 
 Running this command creates the target directory (creating any parent
-directories that don't exist already) and places a ``pyvenv.cfg`` file
-in it with a ``home`` key pointing to the Python installation the
-command was run from.  It also creates a ``bin`` (or ``Scripts`` on
-Windows) subdirectory containing a copy of the ``python`` binary (or
-binaries, in the case of Windows).
-It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
+directories that don't exist already) and places a ``pyvenv.cfg`` file in it
+with a ``home`` key pointing to the Python installation the command was run
+from.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
+containing a copy of the ``python`` binary (or binaries, in the case of
+Windows).  It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
 subdirectory (on Windows, this is ``Lib\site-packages``).
 
 .. highlight:: none
@@ -71,119 +69,131 @@ The command, if run with ``-h``, will show the available options::
       --upgrade              Upgrade the environment directory to use this version
                              of Python, assuming Python has been upgraded in-place.
 
-If the target directory already exists an error will be raised, unless
-the ``--clear`` or ``--upgrade`` option was provided.
+If the target directory already exists an error will be raised, unless the
+``--clear`` or ``--upgrade`` option was provided.
 
 The created ``pyvenv.cfg`` file also includes the
-``include-system-site-packages`` key, set to ``true`` if ``venv`` is
-run with the ``--system-site-packages`` option, ``false`` otherwise.
+``include-system-site-packages`` key, set to ``true`` if ``venv`` is run with
+the ``--system-site-packages`` option, ``false`` otherwise.
 
-Multiple paths can be given to ``pyvenv``, in which case an identical
-virtualenv will be created, according to the given options, at each
-provided path.
+Multiple paths can be given to ``pyvenv``, in which case an identical virtualenv
+will be created, according to the given options, at each provided path.
 
 
 API
 ---
 
+.. highlight:: python
+
 The high-level method described above makes use of a simple API which provides
-mechanisms for third-party virtual environment creators to customize
-environment creation according to their needs.
+mechanisms for third-party virtual environment creators to customize environment
+creation according to their needs, the :class:`EnvBuilder` class.
 
-The :class:`EnvBuilder` class accepts the following keyword arguments on
-instantiation:
+.. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False)
 
-   * ``system_site_packages`` - A Boolean value indicating that the
-     system Python site-packages should be available to the
-     environment (defaults to ``False``).
+    The :class:`EnvBuilder` class accepts the following keyword arguments on
+    instantiation:
 
-   * ``clear`` - A Boolean value which, if True, will delete any
-     existing target directory instead of raising an exception
-     (defaults to ``False``).
+    * ``system_site_packages`` -- a Boolean value indicating that the system Python
+      site-packages should be available to the environment (defaults to ``False``).
 
-   * ``symlinks`` - A Boolean value indicating whether to attempt
-     to symlink the Python binary (and any necessary DLLs or other
-     binaries, e.g. ``pythonw.exe``), rather than copying. Defaults to
-     ``True`` on Linux and Unix systems, but ``False`` on Windows and
-     Mac OS X.
+    * ``clear`` -- a Boolean value which, if True, will delete any existing target
+      directory instead of raising an exception (defaults to ``False``).
 
-The returned env-builder is an object which has a method, ``create``,
-which takes as required argument the path (absolute or relative to the current
-directory) of the target directory which is to contain the virtual environment.
-The ``create`` method will either create the environment in the specified
-directory, or raise an appropriate exception.
+    * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
+      Python binary (and any necessary DLLs or other binaries,
+      e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and
+      Unix systems, but ``False`` on Windows and Mac OS X.
 
-Creators of third-party virtual environment tools will be free to use
-the provided ``EnvBuilder`` class as a base class.
+    .. XXX it also takes "upgrade"!
 
-.. highlight:: python
 
-The ``venv`` module will also provide a module-level function as a
-convenience::
-
-    def create(env_dir,
-               system_site_packages=False, clear=False, symlinks=False):
-        builder = EnvBuilder(
-            system_site_packages=system_site_packages,
-            clear=clear,
-            symlinks=symlinks)
-        builder.create(env_dir)
-
-The ``create`` method of the ``EnvBuilder`` class illustrates the
-hooks available for subclass customization::
-
-    def create(self, env_dir):
-        """
-        Create a virtualized Python environment in a directory.
-        env_dir is the target directory to create an environment in.
-        """
-        env_dir = os.path.abspath(env_dir)
-        context = self.create_directories(env_dir)
-        self.create_configuration(context)
-        self.setup_python(context)
-        self.setup_scripts(context)
-        self.post_setup(context)
-
-Each of the methods ``create_directories``, ``create_configuration``,
-``setup_python``, ``setup_scripts`` and ``post_setup`` can be
-overridden.  The functions of these methods are:
-
-   * ``create_directories`` - creates the environment directory and
-     all necessary directories, and returns a context object. This is
-     just a holder for attributes (such as paths), for use by the
-     other methods.
-
-   * ``create_configuration`` - creates the ``pyvenv.cfg``
-     configuration file in the environment.
-
-   * ``setup_python`` - creates a copy of the Python executable (and,
-     under Windows, DLLs) in the environment.
-
-   * ``setup_scripts`` - Installs activation scripts appropriate to the
-     platform into the virtual environment.
-
-   * ``post_setup`` - A placeholder method which can be overridden
-     in third party implementations to pre-install packages in the
-     virtual environment or perform other post-creation steps.
-
-In addition, ``EnvBuilder`` provides an ``install_scripts`` utility
-method that can be called from ``setup_scripts`` or ``post_setup`` in
-subclasses to assist in installing custom scripts into the virtual
-environment. The method accepts as arguments the context object (see
-above) and a path to a directory. The directory should contain
-subdirectories "common", "posix", "nt", each containing scripts
-destined for the bin directory in the environment. The contents of
-"common" and the directory corresponding to ``os.name`` are copied
-after some text replacement of placeholders:
-
-* ``__VENV_DIR__`` is replaced with the absolute path of the
-  environment directory.
-
-* ``__VENV_NAME__`` is replaced with the environment name (final path
-  segment of environment directory).
-
-* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
-  (either ``bin`` or ``Scripts``).
-
-* ``__VENV_PYTHON__`` is replaced with the absolute path of the
-  environment's executable.
+    Creators of third-party virtual environment tools will be free to use the
+    provided ``EnvBuilder`` class as a base class.
+
+    The returned env-builder is an object which has a method, ``create``:
+
+    .. method:: create(env_dir)
+
+        This method takes as required argument the path (absolute or relative to
+        the current directory) of the target directory which is to contain the
+        virtual environment.  The ``create`` method will either create the
+        environment in the specified directory, or raise an appropriate
+        exception.
+
+        The ``create`` method of the ``EnvBuilder`` class illustrates the hooks
+        available for subclass customization::
+
+            def create(self, env_dir):
+                """
+                Create a virtualized Python environment in a directory.
+                env_dir is the target directory to create an environment in.
+                """
+                env_dir = os.path.abspath(env_dir)
+                context = self.create_directories(env_dir)
+                self.create_configuration(context)
+                self.setup_python(context)
+                self.setup_scripts(context)
+                self.post_setup(context)
+
+        Each of the methods :meth:`create_directories`,
+        :meth:`create_configuration`, :meth:`setup_python`,
+        :meth:`setup_scripts` and :meth:`post_setup` can be overridden.
+
+    .. method:: create_directories(env_dir)
+
+        Creates the environment directory and all necessary directories, and
+        returns a context object.  This is just a holder for attributes (such as
+        paths), for use by the other methods.
+
+    .. method:: create_configuration(context)
+
+        Creates the ``pyvenv.cfg`` configuration file in the environment.
+
+    .. method:: setup_python(context)
+
+        Creates a copy of the Python executable (and, under Windows, DLLs) in
+        the environment.
+
+    .. method:: setup_scripts(context)
+
+        Installs activation scripts appropriate to the platform into the virtual
+        environment.
+
+    .. method:: post_setup(context)
+
+        A placeholder method which can be overridden in third party
+        implementations to pre-install packages in the virtual environment or
+        perform other post-creation steps.
+
+    In addition, :class:`EnvBuilder` provides this utility method that can be
+    called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
+    assist in installing custom scripts into the virtual environment.
+
+    .. method:: install_scripts(context, path)
+
+        *path* is the path to a directory that should contain subdirectories
+        "common", "posix", "nt", each containing scripts destined for the bin
+        directory in the environment.  The contents of "common" and the
+        directory corresponding to :data:`os.name` are copied after some text
+        replacement of placeholders:
+
+        * ``__VENV_DIR__`` is replaced with the absolute path of the environment
+          directory.
+
+        * ``__VENV_NAME__`` is replaced with the environment name (final path
+          segment of environment directory).
+
+        * ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
+          (either ``bin`` or ``Scripts``).
+
+        * ``__VENV_PYTHON__`` is replaced with the absolute path of the
+          environment's executable.
+
+
+There is also a module-level convenience function:
+
+.. function:: create(env_dir, system_site_packages=False, clear=False, symlinks=False)
+
+    Create an :class:`EnvBuilder` with the given keyword arguments, and call its
+    :meth:`~EnvBuilder.create` method with the *env_dir* argument.