[3.13] docs: improve venv docs (GH-124540) (#124727)
docs: improve venv docs (GH-124540)
- 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)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index c0edb3f..e2c7796 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -288,31 +288,31 @@
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
- * ``scm_ignore_files`` -- Create ignore files based for the specified source
+ * *scm_ignore_files* -- Create ignore files based for the specified source
control managers (SCM) in the iterable. Support is defined by having a
method named ``create_{scm}_ignore_file``. The only value supported by
default is ``"git"`` via :meth:`create_git_ignore_file`.
@@ -330,10 +330,7 @@
.. versionchanged:: 3.13
Added the ``scm_ignore_files`` 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)
@@ -433,14 +430,14 @@
.. 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)
@@ -448,22 +445,12 @@
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
@@ -495,6 +482,16 @@
.. versionadded:: 3.13
+ .. 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, \
