[3.12] docs: improve venv docs (GH-124540) (#124728)

- Move "versionchanged" notes that apply to the whole class to the
  end of the class docs
- Remove or move notes next to the method list that apply to individual
  methods.
- Mark up parameters using the appropriate syntax
- Do not capitalize "boolean"
- Shorten some text
(cherry picked from commit c976d789a98047ae7ddec6d13c9ea7086d9fa3f9)

diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 57b0ee7157cf36d8fd181e5d913c5abeeaf4dc41..3bc8faeff05d989a95c3dcfa398d989a082effcc 100644 (file)
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -167,29 +167,29 @@ creation according to their needs, the :class:`EnvBuilder` class.
     The :class:`EnvBuilder` class accepts the following keyword arguments on
     instantiation:
 
-    * ``system_site_packages`` -- a Boolean value indicating that the system Python
+    * *system_site_packages* -- a boolean value indicating that the system Python
       site-packages should be available to the environment (defaults to ``False``).
 
-    * ``clear`` -- a Boolean value which, if true, will delete the contents of
+    * *clear* -- a boolean value which, if true, will delete the contents of
       any existing target directory, before creating the environment.
 
-    * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
+    * *symlinks* -- a boolean value indicating whether to attempt to symlink the
       Python binary rather than copying.
 
-    * ``upgrade`` -- a Boolean value which, if true, will upgrade an existing
+    * *upgrade* -- a boolean value which, if true, will upgrade an existing
       environment with the running Python - for use when that Python has been
       upgraded in-place (defaults to ``False``).
 
-    * ``with_pip`` -- a Boolean value which, if true, ensures pip is
+    * *with_pip* -- a boolean value which, if true, ensures pip is
       installed in the virtual environment. This uses :mod:`ensurepip` with
       the ``--default-pip`` option.
 
-    * ``prompt`` -- a String to be used after virtual environment is activated
+    * *prompt* -- a string to be used after virtual environment is activated
       (defaults to ``None`` which means directory name of the environment would
       be used). If the special string ``"."`` is provided, the basename of the
       current directory is used as the prompt.
 
-    * ``upgrade_deps`` -- Update the base venv modules to the latest on PyPI
+    * *upgrade_deps* -- Update the base venv modules to the latest on PyPI
 
     .. versionchanged:: 3.4
        Added the ``with_pip`` parameter
@@ -200,10 +200,7 @@ creation according to their needs, the :class:`EnvBuilder` class.
     .. versionchanged:: 3.9
        Added the ``upgrade_deps`` parameter
 
-    Creators of third-party virtual environment tools will be free to use the
-    provided :class:`EnvBuilder` class as a base class.
-
-    The returned env-builder is an object which has a method, ``create``:
+    :class:`EnvBuilder` may be used as a base class.
 
     .. method:: create(env_dir)
 
@@ -303,14 +300,14 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
     .. method:: upgrade_dependencies(context)
 
-       Upgrades the core venv dependency packages (currently ``pip``)
+       Upgrades the core venv dependency packages (currently :pypi:`pip`)
        in the environment. This is done by shelling out to the
        ``pip`` executable in the environment.
 
        .. versionadded:: 3.9
        .. versionchanged:: 3.12
 
-          ``setuptools`` is no longer a core venv dependency.
+          :pypi:`setuptools` is no longer a core venv dependency.
 
     .. method:: post_setup(context)
 
@@ -318,22 +315,12 @@ creation according to their needs, the :class:`EnvBuilder` class.
         implementations to pre-install packages in the virtual environment or
         perform other post-creation steps.
 
-    .. versionchanged:: 3.7.2
-       Windows now uses redirector scripts for ``python[w].exe`` instead of
-       copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
-       nothing unless running from a build in the source tree.
-
-    .. versionchanged:: 3.7.3
-       Windows copies the redirector scripts as part of :meth:`setup_python`
-       instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
-       When using symlinks, the original executables will be linked.
-
-    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)
 
+        This method can be
+        called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
+        assist in installing custom scripts into the virtual environment.
+
         *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
@@ -358,6 +345,16 @@ creation according to their needs, the :class:`EnvBuilder` class.
         The directories are allowed to exist (for when an existing environment
         is being upgraded).
 
+    .. versionchanged:: 3.7.2
+       Windows now uses redirector scripts for ``python[w].exe`` instead of
+       copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
+       nothing unless running from a build in the source tree.
+
+    .. versionchanged:: 3.7.3
+       Windows copies the redirector scripts as part of :meth:`setup_python`
+       instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
+       When using symlinks, the original executables will be linked.
+
 There is also a module-level convenience function:
 
 .. function:: create(env_dir, system_site_packages=False, clear=False, \