From 873662179aebbf5eacdf681078f47bbfe5ee6149 Mon Sep 17 00:00:00 2001 From: kpinc Date: Mon, 25 Jun 2018 05:43:59 -0500 Subject: [PATCH] Use Sphinx :pep: syntax to link PEPs (#5491) Creating a news entry from the pull request as a separate commit. Does this warrant an issue? --- docs/reference/pip.rst | 13 +++++-------- docs/reference/pip_install.rst | 11 ++++------- docs/user_guide.rst | 4 +--- news/ed19045b-46b8-4ac0-a98a-60d2afa2c675.trivial | 0 4 files changed, 10 insertions(+), 18 deletions(-) create mode 100644 news/ed19045b-46b8-4ac0-a98a-60d2afa2c675.trivial diff --git a/docs/reference/pip.rst b/docs/reference/pip.rst index 865c64b01..dd68f65ad 100644 --- a/docs/reference/pip.rst +++ b/docs/reference/pip.rst @@ -72,7 +72,7 @@ Build System Interface ====================== Pip builds packages by invoking the build system. Presently, the only supported -build system is ``setuptools``, but in the future, pip will support `PEP517`_ +build system is ``setuptools``, but in the future, pip will support :pep:`517` which allows projects to specify an alternative build system in a ``pyproject.toml`` file. As well as package building, the build system is also invoked to install packages direct from source. This is handled by invoking @@ -118,7 +118,7 @@ PEP 518 Support As of 10.0, pip supports projects declaring dependencies that are required at install time using a ``pyproject.toml`` file, in the form described in -`PEP518`_. When building a project, pip will install the required dependencies +:pep:`518`. When building a project, pip will install the required dependencies locally, and make them available to the build process. When making build requirements available, pip does so in an *isolated @@ -141,7 +141,7 @@ appropriately. **Limitations**: -* until `PEP517`_ support is added, ``setuptools`` and ``wheel`` **must** be +* until :pep:`517` support is added, ``setuptools`` and ``wheel`` **must** be included in the list of build requirements: pip will assume these as default, but will not automatically add them to the list of build requirements if explicitly defined in ``pyproject.toml``. @@ -149,7 +149,7 @@ appropriately. * the current implementation only support installing build requirements from wheels: this is a technical limitation of the implementation - source installs would require a build step of their own, potentially recursively - triggering another `PEP518`_ dependency installation process. The possible + triggering another :pep:`518` dependency installation process. The possible unbounded recursion involved was not considered acceptable, and so installation of build dependencies from source has been disabled until a safe resolution of this issue is found. @@ -157,13 +157,11 @@ appropriately. * ``pip<18.0`` does not support the use of environment markers and extras, only version specifiers are respected. -.. _PEP517: https://www.python.org/dev/peps/pep-0517/ -.. _PEP518: https://www.python.org/dev/peps/pep-0518/ Future Developments ~~~~~~~~~~~~~~~~~~~ -`PEP426`_ notes that the intention is to add hooks to project metadata in +:pep:`426` notes that the intention is to add hooks to project metadata in version 2.1 of the metadata spec, to explicitly define how to build a project from its source. Once this version of the metadata spec is final, pip will migrate to using that interface. At that point, the ``setup.py`` interface @@ -173,7 +171,6 @@ have migrated. Specifically, applications should *not* expect to rely on there being any form of backward compatibility guarantees around the ``setup.py`` interface. -.. _PEP426: https://www.python.org/dev/peps/pep-0426/#metabuild-system Build Options ~~~~~~~~~~~~~ diff --git a/docs/reference/pip_install.rst b/docs/reference/pip_install.rst index 76a9b4bb0..66f749252 100644 --- a/docs/reference/pip_install.rst +++ b/docs/reference/pip_install.rst @@ -38,7 +38,7 @@ each is, in the following order: 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 requirement, as specified in :pep:`440`. Each item identified is added to the set of requirements to be satisfied by the install. @@ -237,7 +237,7 @@ Requirement Specifiers pip supports installing from a package index using a :term:`requirement specifier `. Generally speaking, a requirement specifier is composed of a project name followed by optional :term:`version -specifiers `. `PEP508`_ contains a full specification +specifiers `. :pep:`508` contains a full specification of the format of a requirement (``pip`` does not support the ``url_req`` form of specifier at this time). @@ -311,7 +311,7 @@ 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 `PEP440`_ +`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. If a Requirement specifier includes a pre-release or development version @@ -484,7 +484,7 @@ 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 `PEP440`_ for +match for the requirements (in terms of version number - see :pep:`440` for details) is selected. See the :ref:`pip install Examples`. @@ -881,6 +881,3 @@ Examples .. [1] This is true with the exception that pip v7.0 and v7.0.1 required quotes around specifiers containing environment markers in requirement files. - -.. _PEP440: https://www.python.org/dev/peps/pep-0440/ -.. _PEP508: https://www.python.org/dev/peps/pep-0508/ diff --git a/docs/user_guide.rst b/docs/user_guide.rst index ba7ecb880..8f5326643 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -176,9 +176,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 `_ , -`PEP427 `_, and -`PEP425 `_ +`Wheel docs `_ , :pep:`427`, and :pep:`425`. Pip prefers Wheels where they are available. To disable this, use the :ref:`--no-binary ` flag for :ref:`pip install`. diff --git a/news/ed19045b-46b8-4ac0-a98a-60d2afa2c675.trivial b/news/ed19045b-46b8-4ac0-a98a-60d2afa2c675.trivial new file mode 100644 index 000000000..e69de29bb