[3.13] gh-130160: use .. program:: directive for documenting venv CLI (GH-130699) (#136551)

gh-130160: use `.. program::` directive for documenting `venv` CLI (GH-130699)
(cherry picked from commit fb9f933)

Co-authored-by: Kanishk Pachauri <[email protected]>
Co-authored-by: Semyon Moroz <[email protected]>
Co-authored-by: Bénédikt Tran <[email protected]>

Author: 4 people

Doc/library/venv.rst

@@ -102,36 +102,52 @@ The command, if run with ``-h``, will show the available options::
 
    Creates virtual Python environments in one or more target directories.
 
-   positional arguments:
-     ENV_DIR               A directory to create the environment in.
-
-   options:
-     -h, --help            show this help message and exit
-     --system-site-packages
-                           Give the virtual environment access to the system
-                           site-packages dir.
-     --symlinks            Try to use symlinks rather than copies, when
-                           symlinks are not the default for the platform.
-     --copies              Try to use copies rather than symlinks, even when
-                           symlinks are the default for the platform.
-     --clear               Delete the contents of the environment directory
-                           if it already exists, before environment creation.
-     --upgrade             Upgrade the environment directory to use this
-                           version of Python, assuming Python has been
-                           upgraded in-place.
-     --without-pip         Skips installing or upgrading pip in the virtual
-                           environment (pip is bootstrapped by default)
-     --prompt PROMPT       Provides an alternative prompt prefix for this
-                           environment.
-     --upgrade-deps        Upgrade core dependencies (pip) to the latest
-                           version in PyPI
-     --without-scm-ignore-files
-                           Skips adding SCM ignore files to the environment
-                           directory (Git is supported by default).
-
    Once an environment has been created, you may wish to activate it, e.g. by
    sourcing an activate script in its bin directory.
 
+.. _venv-cli:
+.. program:: venv
+
+.. 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``