Merge pull request #12434 from jeanas/pep-refs

Improve documentation usability by turning some PEP numbers into PUG links

Author: pradyunsg

NEWS.rst

@@ -106,8 +106,9 @@ Process
 Deprecations and Removals
 -------------------------
 
-- Deprecate legacy version and version specifiers that don't conform to `PEP 440
-  <https://peps.python.org/pep-0440/>`_ (`#12063 <https://github.com/pypa/pip/issues/12063>`_)
+- Deprecate legacy version and version specifiers that don't conform to the
+  :ref:`specification <pypug:version-specifiers>`.
+  (`#12063 <https://github.com/pypa/pip/issues/12063>`_)
 - ``freeze`` no longer excludes the ``setuptools``, ``distribute``, and ``wheel``
   from the output when running on Python 3.12 or later, where they are not
   included in a virtual environment by default. Use ``--exclude`` if you wish to

docs/html/cli/pip_install.rst

@@ -49,7 +49,7 @@ each is, in the following order:
    otherwise pip will report an error).
 3. Local file (a sdist or wheel format archive, following the naming
    conventions for those formats).
-4. A requirement, as specified in :pep:`440`.
+4. A :ref:`version specifier <pypug:version-specifiers>`.
 
 Each item identified is added to the set of requirements to be satisfied by
 the install.
@@ -97,7 +97,8 @@ Installation Order
 .. note::
 
    This section is only about installation order of runtime dependencies, and
-   does not apply to build dependencies (those are specified using PEP 518).
+   does not apply to build dependencies (those are specified using the
+   :ref:`[build-system] table <pypug:pyproject-build-system-table>`).
 
 As of v6.1.0, pip installs dependencies before their dependents, i.e. in
 "topological order."  This is the only commitment pip currently makes related
@@ -181,8 +182,9 @@ Pre-release Versions
 --------------------
 
 Starting with v1.4, pip will only install stable versions as specified by
-`pre-releases`_ by default. If a version cannot be parsed as a compliant :pep:`440`
-version then it is assumed to be a pre-release.
+`pre-releases`_ by default. If a version cannot be parsed as a
+:ref:`compliant <pypug:version-specifiers>` version then it is assumed to be
+a pre-release.
 
 If a Requirement specifier includes a pre-release or development version
 (e.g. ``>=0.0.dev0``) then pip will allow pre-release and development versions
@@ -214,8 +216,8 @@ pip looks for packages in a number of places: on PyPI (if not disabled via
 ``--no-index``), in the local filesystem, and in any additional repositories
 specified via ``--find-links`` or ``--index-url``. There is no ordering in
 the locations that are searched. Rather they are all checked, and the "best"
-match for the requirements (in terms of version number - see :pep:`440` for
-details) is selected.
+match for the requirements (in terms of version number - see the
+:ref:`specification <pypug:version-specifiers>` for details) is selected.
 
 See the :ref:`pip install Examples<pip install Examples>`.
 
@@ -380,7 +382,8 @@ Examples
          py -m pip install -e "git+https://git.repo/some_pkg.git@feature#egg=SomePackage"  # from 'feature' branch
          py -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory
 
-#. Install a package with `extras`_.
+#. Install a package with extras, i.e., optional dependencies
+   (:ref:`specification <pypug:dependency-specifiers>`).
 
    .. tab:: Unix/macOS
 
@@ -418,7 +421,8 @@ Examples
          py -m pip install "./downloads/SomePackage-1.0.4.tar.gz"
          py -m pip install "http://my.package.repo/SomePackage-1.0.4.zip"
 
-#. Install a particular source archive file following :pep:`440` direct references.
+#. Install a particular source archive file following direct references
+   (:ref:`specification <pypug:dependency-specifiers>`).
 
    .. tab:: Unix/macOS
 
@@ -539,5 +543,4 @@ Examples
 
          py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1
 
-.. _extras: https://www.python.org/dev/peps/pep-0508/#extras
 .. _PyPI: https://pypi.org/

docs/html/cli/pip_wheel.rst

@@ -34,7 +34,8 @@ Differences to ``build``
 ------------------------
 
 `build <https://pypi.org/project/build/>`_ is a simple tool which can among other things build
-wheels for projects using PEP 517. It is comparable to the execution of ``pip wheel --no-deps .``.
+wheels for projects using the standard ``pyproject.toml``-based build interface. It
+is comparable to the execution of ``pip wheel --no-deps .``.
 It can also build source distributions which is not possible with ``pip``.
 ``pip wheel`` covers the wheel scope of ``build`` but offers many additional features.
 

docs/html/development/architecture/package-finding.rst

@@ -182,8 +182,9 @@ example, whether a pre-release is eligible for selection or whether a file
 whose hash doesn't match is eligible depends on properties of the collection
 as a whole.
 
-The ``CandidateEvaluator`` class uses information like the list of `PEP 425`_
-tags compatible with the target Python interpreter, hashes provided by the
+The ``CandidateEvaluator`` class uses information like the list of
+:ref:`platform tags <pypug:platform-compatibility-tags>`
+compatible with the target Python interpreter, hashes provided by the
 user, and other user preferences, etc.
 
 Specifically, the class has a ``get_applicable_candidates()`` method.
@@ -236,5 +237,4 @@ The class is the return type of both the ``CandidateEvaluator`` class's
 ``find_best_candidate()`` method.
 
 
-.. _`PEP 425`: https://www.python.org/dev/peps/pep-0425/
 .. _`PEP 503`: https://www.python.org/dev/peps/pep-0503/

docs/html/development/getting-started.rst

@@ -206,7 +206,6 @@ in order to start contributing.
 
 .. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Trouble+with+pip+development+environment
 .. _`install Python`: https://realpython.com/installing-python/
-.. _`PEP 484 type-comments`: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
 .. _`rich CLI`: https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests
 .. _`GitHub`: https://github.com/pypa/pip
 .. _`good first issues`: https://github.com/pypa/pip/labels/good%20first%20issue

docs/html/reference/inspect-report.md

@@ -27,9 +27,8 @@ The report is a JSON object with the following properties:
   distribution packages that are installed.
 
 - `environment`: an object describing the environment where the installation report was
-  generated. See [PEP 508 environment
-  markers](https://peps.python.org/pep-0508/#environment-markers) for more information.
-  Values have a string type.
+  generated. See the section on environment markers in the {ref}`pypug:dependency-specifiers`
+  specification for more information. Values have a string type.
 
 (InspectReportItem)=
 

docs/html/topics/more-dependency-resolution.md

@@ -97,10 +97,10 @@ feeding candidates to the resolver, and has a key role to play in selecting
 suitable candidates.
 
 Note that the resolver is *only* relevant for packages fetched from an index.
-Candidates coming from other sources (local source directories, PEP 508
-direct URL references) do *not* go through the finder, and are merged with the
-candidates provided by the finder as part of the resolver's "provider"
-implementation.
+Candidates coming from other sources (local source directories, {ref}`direct
+URL references <pypug:dependency-specifiers>`) do *not* go through the finder,
+and are merged with the candidates provided by the finder as part of the resolver's
+"provider" implementation.
 
 As well as determining what versions exist in the index for a given project,
 the finder selects the best distribution file to use for that candidate. This

docs/html/topics/vcs-support.md

@@ -140,9 +140,8 @@ pip also looks at the `egg` fragment specifying the "project name". In practice
 mode. In all other circumstances, the `egg` fragment is not necessary and its use is
 discouraged.
 
-The `egg` fragment **should** be a bare
-[PEP 508](https://peps.python.org/pep-0508/) project name. Anything else
-is not guaranteed to work.
+The `egg` fragment **should** be a bare {ref}`project name <pypug:name-normalization>`.
+Anything else is not guaranteed to work.
 
 ````{admonition} Example
 If your repository layout is:

docs/html/user_guide.rst

@@ -264,7 +264,7 @@ Installing from Wheels
 
 "Wheel" is a built, archive format that can greatly speed installation compared
 to building and installing from source archives. For more information, see the
-`Wheel docs <https://wheel.readthedocs.io>`_ , :pep:`427`, and :pep:`425`.
+:ref:`specification <pypug:binary-distribution-format>`.
 
 pip prefers Wheels where they are available. To disable this, use the
 :ref:`--no-binary <install_--no-binary>` flag for :ref:`pip install`.
@@ -306,7 +306,8 @@ name:
 .. note::
 
     In the future, the ``path[extras]`` syntax may become deprecated. It is
-    recommended to use PEP 508 syntax wherever possible.
+    recommended to use :ref:`standard <pypug:dependency-specifiers>`
+    syntax wherever possible.
 
 For the cases where wheels are not available, pip offers :ref:`pip wheel` as a
 convenience, to build wheels for all your requirements and dependencies.

news/12434.doc.rst

@@ -0,0 +1 @@
+Replace some links to PEPs with links to the canonical specifications on the :doc:`pypug:index`