Skip to content

gh-130160: use .. program:: directive for documenting venv CLI #130699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+42 −15
Open

gh-130160: use .. program:: directive for documenting venv CLI #130699

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4dc832e
gh-130160 use `.. program::` directive for documenting `venv` CLI
Mr-Sunglasses Feb 28, 2025
c8ee8c3
Merge branch 'main' into venv-use-prog
Mr-Sunglasses Mar 3, 2025
a4df05e
Merge branch 'main' into venv-use-prog
Mr-Sunglasses Apr 5, 2025
1419051
Update Doc/library/venv.rst
Mr-Sunglasses Apr 5, 2025
918676c
Update Doc/library/venv.rst
Mr-Sunglasses Apr 5, 2025
f0285a2
Merge branch 'main' into venv-use-prog
Mr-Sunglasses Apr 5, 2025
34753d4
Merge branch 'main' into venv-use-prog
Mr-Sunglasses Apr 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 42 additions & 15 deletions Doc/library/venv.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,8 @@ See :pep:`405` for more background on Python virtual environments.

Creating virtual environments
-----------------------------
.. _venv-cli:
.. program:: venv

:ref:`Virtual environments <venv-def>` are created by executing the ``venv``
module:
Expand All @@ -81,21 +83,6 @@ It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory
(on Windows, this is :file:`Lib\site-packages`).
If an existing directory is specified, it will be re-used.

.. versionchanged:: 3.5
The use of ``venv`` is now recommended for creating virtual environments.

.. deprecated-removed:: 3.6 3.8
:program:`pyvenv` was the recommended tool for creating virtual environments
for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly.
Comment on lines -84 to -89
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this removed?


.. highlight:: none

On Windows, invoke the ``venv`` command as follows:

.. code-block:: ps1con

PS> python -m venv C:\path\to\new\virtual\environment
Comment on lines -95 to -97
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this removed?


The command, if run with ``-h``, will show the available options::

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
Comment on lines 86 to 88
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Mr-Sunglasses I understood that the problem is that there is duplicate information about venv cli (you didn't replace it, you just added a new one, check these lines and below)

could you remove it leaving only the use of .. option:: directives?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could you remove it leaving only the use of .. option:: directives?

There should IMO be something that shows how to invoke it, e.g. python -m venv [options] [VENV_DIR ...] appropriately marked up to be as prominent/compatibly styled to the option directive rendering.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are absolutely right. I forgot about it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, I suggest shortening the help. Currently it's as follows:

image

Instead I suggest we only keep

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            [--without-scm-ignore-files]
            ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target directories.
...
Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and maybe it would be better to remove following text from code block:

Creates virtual Python environments in one or more target directories.
...
Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

Expand Down Expand Up @@ -135,6 +122,46 @@ The command, if run with ``-h``, will show the available options::
Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

.. option:: ENV_DIR

A required argument specifying the directory to create the environment in.

.. option:: --system-site-packages

Give the virtual environment access to the system site-packages directory.

.. option:: --symlinks

Try to use symlinks rather than copies, when symlinks are not the default for the platform.

.. option:: --copies

Try to use copies rather than symlinks, even when symlinks are the default for the platform.

.. option:: --clear

Delete the contents of the environment directory if it already exists, before environment creation.

.. option:: --upgrade

Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place.

.. option:: --without-pip

Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default).

.. option:: --prompt <PROMPT>

Provides an alternative prompt prefix for this environment.

.. option:: --upgrade-deps

Upgrade core dependencies (pip) to the latest version in PyPI.

.. option:: --without-scm-ignore-files

Skips adding SCM ignore files to the environment directory (Git is supported by default).


.. versionchanged:: 3.4
Installs pip by default, added the ``--without-pip`` and ``--copies``
Expand Down
Loading