Merge branch 'pypa:main' into main

dukecat0 · web-flow · commit 0ef3d3fb6525 · 2021-08-27T20:17:14.000+08:00
diff --git a/source/discussions/pip-vs-easy-install.rst b/source/discussions/pip-vs-easy-install.rst
@@ -65,7 +65,7 @@ Here's a breakdown of the important differences between pip and the deprecated e
 
 .. _deprecated: https://setuptools.readthedocs.io/en/latest/history.html#v42-0-0
 
-.. [1] https://setuptools.readthedocs.io/en/latest/easy_install.html#natural-script-launcher
+.. [1] https://setuptools.readthedocs.io/en/latest/deprecated/easy_install.html#natural-script-launcher
 
 
 .. _pylauncher support: https://bitbucket.org/vinay.sajip/pylauncher
diff --git a/source/glossary.rst b/source/glossary.rst
@@ -42,9 +42,8 @@ Glossary
     Egg
 
         A :term:`Built Distribution` format introduced by :ref:`setuptools`,
-        which is being replaced by :term:`Wheel`.  For details, see `The
-        Internal Structure of Python Eggs
-        <https://setuptools.readthedocs.io/en/latest/deprecated/python_eggs.html>`_ and
+        which is being replaced by :term:`Wheel`.  For details, see `
+        :doc:`The Internal Structure of Python Eggs <setuptools:deprecated/python_eggs>` and
         `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_
 
     Extension Module
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -509,8 +509,8 @@ points (see below).
 Use this keyword to specify any plugins that your project provides for any named
 entry points that may be defined by your project or others that you depend on.
 
-For more information, see the section on `Advertising Behavior
-<https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html#dynamic-discovery-of-services-and-plugins>`_
+For more information, see the section on
+:ref:`Advertising Behavior <setuptools:dynamic discovery of services and plugins>`
 from the :ref:`setuptools` docs.
 
 The most commonly used entry point is "console_scripts" (see below).
@@ -528,16 +528,16 @@ The most commonly used entry point is "console_scripts" (see below).
       ],
   },
 
-Use ``console_script`` `entry points
-<https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_
+Use ``console_script``
+:ref:`entry points <setuptools:dynamic discovery of services and plugins>`
 to register your script interfaces. You can then let the toolchain handle the
 work of turning these interfaces into actual scripts [2]_.  The scripts will be
 generated during the install of your :term:`distribution <Distribution
 Package>`.
 
 For more information, see `Automatic Script Creation
 <https://setuptools.readthedocs.io/en/latest/setuptools.html#automatic-script-creation>`_
-from the `setuptools docs <https://setuptools.readthedocs.io>`_.
+from the :doc:`setuptools docs <setuptools:index>`.
 
 .. _`Choosing a versioning scheme`:
 
@@ -706,9 +706,9 @@ Lastly, if you don't want to install any dependencies at all, you can run:
    python -m pip install -e . --no-deps
 
 
-For more information, see the `Development Mode
-<https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_ section
-of the `setuptools docs <https://setuptools.readthedocs.io>`_.
+For more information, see the
+:doc:`<Development Mode <setuptools:userguide/development_mode>` section
+of the :doc:`setuptools docs <setuptools>`.
 
 .. _`Packaging your project`:
 
diff --git a/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml b/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml
@@ -9,10 +9,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@master
-    - name: Set up Python 3.7
+    - name: Set up Python 3.9
       uses: actions/setup-python@v1
       with:
-        python-version: 3.7
+        python-version: 3.9
     - name: Install pypa/build
       run: >-
         python -m
diff --git a/source/guides/index-mirrors-and-caches.rst b/source/guides/index-mirrors-and-caches.rst
@@ -29,8 +29,7 @@ Caching with pip
 pip provides a number of facilities for speeding up installation by using local
 cached copies of :term:`packages <Distribution Package>`:
 
-1. `Fast & local installs
-   <https://pip.pypa.io/en/latest/user_guide/#installing-from-local-packages>`_
+1. :ref:`Fast & local installs <pip:installing from local packages>`
    by downloading all the requirements for a project and then pointing pip at
    those downloaded files instead of going to PyPI.
 2. A variation on the above which pre-builds the installation files for
diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -323,7 +323,8 @@ pip can install a package directly from source, for example:
         cd google-auth
         py -m pip install .
 
-Additionally, pip can install packages from source in `development mode`_,
+Additionally, pip can install packages from source in
+:doc:`development mode <setuptools:userguide/development_mode>`,
 meaning that changes to the source directory will immediately affect the
 installed package without needing to re-install:
 
@@ -339,9 +340,6 @@ installed package without needing to re-install:
 
         py -m pip install --editable .
 
-.. _development mode:
-    https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode
-
 
 Installing from version control systems
 ---------------------------------------
diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
@@ -221,9 +221,9 @@ above to make the interface available as an importable Python module.
 Implementing binary extensions
 ==============================
 
-The CPython `Extending and Embedding <https://docs.python.org/3/extending/>`_
+The CPython :doc:`Extending and Embedding <python:extending/index>`
 guide includes an introduction to writing a
-`custom extension module in C <https://docs.python.org/3/extending/extending.html>`_.
+:doc:`custom extension module in C <python:extending/extending>`.
 
 ::
 
diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
@@ -128,8 +128,8 @@ the `native namespace package example project`_.
 pkgutil-style namespace packages
 --------------------------------
 
-Python 2.3 introduced the `pkgutil`_ module and the
-`extend_path`_ function. This can be used to declare namespace
+Python 2.3 introduced the :doc:`pkgutil <python:library/pkgutil>` module and the
+:py:func:`python:pkgutil.extend_path` function. This can be used to declare namespace
 packages that need to be compatible with both Python 2.3+ and Python 3. This
 is the recommended approach for the highest level of compatibility.
 
@@ -160,7 +160,6 @@ additional code in :file:`__init__.py` will be inaccessible.
 A complete working example of two pkgutil-style namespace packages can be found
 in the `pkgutil namespace example project`_.
 
-.. _pkgutil: https://docs.python.org/3/library/pkgutil.html
 .. _extend_path:
     https://docs.python.org/3/library/pkgutil.html#pkgutil.extend_path
 .. _pkgutil namespace example project:
diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -90,7 +90,7 @@ Then, add the following under the ``build-n-publish`` section:
    :end-before: Install pypa/build
 
 This will download your repository into the CI runner and then
-install and activate Python 3.7.
+install and activate Python 3.9.
 
 And now we can build dists from source. In this example, we'll
 use ``build`` package, assuming that your project has a
@@ -107,7 +107,7 @@ So add this to the steps list:
 
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
-   :start-after: version: 3.7
+   :start-after: version: 3.9
    :end-before: Actually publish to PyPI/TestPyPI
 
 
diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
@@ -31,8 +31,8 @@ Installation tool recommendations
   is installed, you may need to also install :ref:`wheel` to get the benefit
   of wheel caching. [3]_
 
-* Use :ref:`virtualenv`, or `venv`_ to isolate application specific
-  dependencies from a shared Python installation. [4]_
+* Use :ref:`virtualenv`, or :doc:`venv <python:library/venv>` to isolate application
+  specific dependencies from a shared Python installation. [4]_
 
 * If you're looking for management of fully integrated cross-platform software
   stacks, consider:
@@ -111,4 +111,3 @@ migration, and what settings to change in your clients.
        choice for packaging.
 
 .. _distribute: https://pypi.org/project/distribute
-.. _venv: https://docs.python.org/3/library/venv.html
diff --git a/source/overview.rst b/source/overview.rst
@@ -94,8 +94,8 @@ you can use Python's native packaging tools to create a *source*
 
 Python's *sdists* are compressed archives (``.tar.gz`` files)
 containing one or more packages or modules. If your code is
-pure-Python, and you only depend on other Python packages, you can `go
-here to learn more <https://docs.python.org/3/distutils/sourcedist.html>`_.
+pure-Python, and you only depend on other Python packages, you can
+:doc:`go here to learn more <python:distutils/sourcedist>`.
 
 If you rely on any non-Python code, or non-Python packages (such as
 `libxml2 <https://en.wikipedia.org/wiki/Libxml2>`_ in the case of
@@ -166,8 +166,8 @@ audience.
 Python's native packaging is mostly built for distributing reusable
 code, called libraries, between developers. You can piggyback
 **tools**, or basic applications for developers, on top of Python's
-library packaging, using technologies like `setuptools entry_points
-<https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html>`_.
+library packaging, using technologies like
+:doc:`setuptools entry_points <userguide/entry_point>`.
 
 Libraries are building blocks, not complete applications. For
 distributing applications, there's a whole new world of technologies
@@ -249,7 +249,7 @@ machines of developers and data scientists.
 Technologies which support this model:
 
 * `PEX <https://github.com/pantsbuild/pex#pex>`_ (Python EXecutable)
-* `zipapp <https://docs.python.org/3/library/zipapp.html>`_ (does not help manage dependencies, requires Python 3.5+)
+* :doc:`zipapp <python:library/zipapp>` (does not help manage dependencies, requires Python 3.5+)
 * `shiv <https://github.com/linkedin/shiv#shiv>`_ (requires Python 3)
 
 .. note:: Of all the approaches here, depending on a pre-installed
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
@@ -178,7 +178,7 @@ Optionally, create a virtual environment
 ----------------------------------------
 
 See :ref:`section below <Creating and using Virtual Environments>` for details,
-but here's the basic `venv`_ [3]_ command to use on a typical Linux system:
+but here's the basic :doc:`venv <python:library/venv>` [3]_ command to use on a typical Linux system:
 
 .. tab:: Unix/macOS
 
@@ -228,7 +228,7 @@ environments.
 
 Currently, there are two common tools for creating Python virtual environments:
 
-* `venv`_ is available by default in Python 3.3 and later, and installs
+* :doc:`venv <python:library/venv>` is available by default in Python 3.3 and later, and installs
   :ref:`pip` and :ref:`setuptools` into created virtual environments in
   Python 3.4 and later.
 * :ref:`virtualenv` needs to be installed separately, but supports Python 2.7+
@@ -238,7 +238,7 @@ Currently, there are two common tools for creating Python virtual environments:
 
 The basic usage is like so:
 
-Using `venv`_:
+Using :doc:`venv <python:library/venv>`:
 
 .. tab:: Unix/macOS
 
@@ -270,7 +270,8 @@ Using :ref:`virtualenv`:
         virtualenv <DIR>
         <DIR>\Scripts\activate
 
-For more information, see the `venv`_ docs or the `virtualenv <http://virtualenv.pypa.io>`_ docs.
+For more information, see the :doc:`venv <python:library/venv>` docs or
+the `virtualenv <http://virtualenv.pypa.io>`_ docs.
 
 The use of :command:`source` under Unix shells ensures
 that the virtual environment's variables are set within the current
@@ -297,7 +298,7 @@ Use pip for Installing
 ======================
 
 :ref:`pip` is the recommended installer.  Below, we'll cover the most common
-usage scenarios. For more detail, see the `pip docs <https://pip.pypa.io>`_,
+usage scenarios. For more detail, see the :doc:`pip docs <pip:index>`,
 which includes a complete :doc:`Reference Guide <pip:cli/index>`.
 
 
@@ -542,8 +543,8 @@ Installing from a local src tree
 ================================
 
 
-Installing from local src in `Development Mode
-<https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_,
+Installing from local src in
+:doc:`Development Mode <setuptools:userguide/development_mode>`,
 i.e. in such a way that the project appears to be installed, but yet is
 still editable from the src tree.
 
@@ -682,5 +683,4 @@ Install `setuptools extras`_.
        and support was released in :ref:`setuptools` v8.0 and
        :ref:`pip` v6.0
 
-.. _venv: https://docs.python.org/3/library/venv.html
 .. _setuptools extras: https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
diff --git a/source/tutorials/managing-dependencies.rst b/source/tutorials/managing-dependencies.rst
@@ -53,12 +53,12 @@ Use ``pip`` to install Pipenv:
 
 .. Note:: This does a `user installation`_ to prevent breaking any system-wide
     packages. If ``pipenv`` isn't available in your shell after installation,
-    you'll need to add the `user base`_'s binary directory to your ``PATH``.
+    you'll need to add the :py:data:`user base <python:site.USER_BASE>`'s
+    binary directory to your ``PATH``.
     See :ref:`Installing to the User Site` for more information.
 
 .. _npm: https://www.npmjs.com/
 .. _bundler: http://bundler.io/
-.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
 .. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
 
 Installing packages for your project
