Merge branch 'master' into pep643

pfmoore · pfmoore · commit 75c4acc1b962 · 2021-01-01T13:21:49.000Z
diff --git a/source/conf.py b/source/conf.py
@@ -196,8 +196,8 @@
 
 # Custom sidebar templates, filenames relative to this file.
 html_sidebars = {
-    '**': ['localtoc.html', 'relations.html'],
-    'index': ['localtoc.html']
+    '**': ['globaltoc.html', 'relations.html'],
+    'index': ['globaltoc.html']
 }
 
 # Additional templates that should be rendered to pages, maps page names to
diff --git a/source/discussions/pip-vs-easy-install.rst b/source/discussions/pip-vs-easy-install.rst
@@ -6,12 +6,12 @@ pip vs easy_install
 ===================
 
 
-`easy_install` was released in 2004, as part of :ref:`setuptools`.  It was
+:ref:`easy_install <easy_install>` was released in 2004, as part of :ref:`setuptools`.  It was
 notable at the time for installing :term:`packages <Distribution Package>` from
 :term:`PyPI <Python Package Index (PyPI)>` using requirement specifiers, and
 automatically installing dependencies.
 
-:ref:`pip` came later in 2008, as alternative to `easy_install`, although still
+:ref:`pip` came later in 2008, as alternative to :ref:`easy_install <easy_install>`, although still
 largely built on top of :ref:`setuptools` components.  It was notable at the
 time for *not* installing packages as :term:`Eggs <Egg>` or from :term:`Eggs <Egg>` (but
 rather simply as 'flat' packages from :term:`sdists <Source Distribution (or
diff --git a/source/glossary.rst b/source/glossary.rst
@@ -44,7 +44,7 @@ Glossary
         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/formats.html>`_ and
+        <https://setuptools.readthedocs.io/en/latest/deprecated/python_eggs.html>`_ and
         `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_
 
     Extension Module
diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
@@ -113,7 +113,7 @@ The following query counts the total number of downloads for the project
       -- Only query the last 30 days of history
       AND DATE(timestamp)
         BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
-        AND CURRENT_DATE())
+        AND CURRENT_DATE()
 
 +---------------+
 | num_downloads |
@@ -134,7 +134,7 @@ column.
       -- Only query the last 30 days of history
       AND DATE(timestamp)
         BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
-        AND CURRENT_DATE())
+        AND CURRENT_DATE()
 
 +---------------+
 | num_downloads |
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -508,9 +508,8 @@ entry_points
 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 `Dynamic Discovery of Services and
-Plugins
-<https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_
+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>`_
 from the :ref:`setuptools` docs.
 
 The most commonly used entry point is "console_scripts" (see below).
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
@@ -13,28 +13,28 @@ jobs:
       uses: actions/setup-python@v1
       with:
         python-version: 3.7
-    - name: Install pep517
+    - name: Install pypa/build
       run: >-
         python -m
         pip install
-        pep517
+        build
         --user
     - name: Build a binary wheel and a source tarball
       run: >-
         python -m
-        pep517.build
-        --source
-        --binary
-        --out-dir dist/
+        build
+        --sdist
+        --wheel
+        --outdir dist/
         .
     # Actually publish to PyPI/TestPyPI
     - name: Publish distribution 📦 to Test PyPI
       uses: pypa/gh-action-pypi-publish@master
       with:
-        password: ${{ secrets.test_pypi_password }}
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
         repository_url: https://test.pypi.org/legacy/
     - name: Publish distribution 📦 to PyPI
       if: startsWith(github.ref, 'refs/tags')
       uses: pypa/gh-action-pypi-publish@master
       with:
-        password: ${{ secrets.pypi_password }}
+        password: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/source/guides/index.rst b/source/guides/index.rst
@@ -7,13 +7,20 @@ introduction to packaging, see :doc:`/tutorials/index`.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Installing Packages:
 
-   tool-recommendations
    installing-using-pip-and-virtual-environments
    installing-stand-alone-command-line-tools
    installing-using-linux-tools
    installing-scientific-packages
    multi-version-installs
+   index-mirrors-and-caches
+   hosting-your-own-index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Building and Publishing Projects:
+
    distributing-packages-using-setuptools
    using-manifest-in
    single-sourcing-package-version
@@ -23,10 +30,14 @@ introduction to packaging, see :doc:`/tutorials/index`.
    supporting-windows-using-appveyor
    packaging-namespace-packages
    creating-and-discovering-plugins
-   analyzing-pypi-package-downloads
-   index-mirrors-and-caches
-   hosting-your-own-index
    migrating-to-pypi-org
    using-testpypi
    making-a-pypi-friendly-readme
    publishing-package-distribution-releases-using-github-actions-ci-cd-workflows
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Miscellaneous:
+
+   tool-recommendations
+   analyzing-pypi-package-downloads
diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
@@ -98,7 +98,7 @@ To install pip, wheel, and setuptools, in a parallel, non-system environment
 (using yum) then there are two options:
 
 
-1. Use the "Sofware Collections" feature to enable a parallel collection that
+1. Use the "Software Collections" feature to enable a parallel collection that
    includes pip, setuptools, and wheel.
 
    * For Redhat, see here:
diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -7,7 +7,7 @@ for Python 2. These are the lowest-level tools for managing Python
 packages and are recommended if higher-level tools do not suit your needs.
 
 .. note:: This doc uses the term **package** to refer to a
-    :term:`Distribution Package`  which is different from a :term:`Import
+    :term:`Distribution Package`  which is different from an :term:`Import
     Package` that which is used to import modules in your Python source code.
 
 
diff --git a/source/guides/multi-version-installs.rst b/source/guides/multi-version-installs.rst
@@ -32,7 +32,7 @@ This can be worked around by setting all dependencies in
 ``__main__.__requires__`` before importing ``pkg_resources`` for the first
 time, but that approach does mean that standard command line invocations of
 the affected tools can't be used - it's necessary to write a custom
-wrapper script or use ``python -c '<commmand>'`` to invoke the application's
+wrapper script or use ``python -c '<command>'`` to invoke the application's
 main entry point directly.
 
 Refer to the `pkg_resources documentation
diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
@@ -112,7 +112,7 @@ profiling has identified the code where the speed increase is worth
 additional maintenance effort), a number of other alternatives should
 also be considered:
 
-* look for existing optimised alternatives. The CPython standard libary
+* look for existing optimised alternatives. The CPython standard library
   includes a number of optimised data structures and algorithms (especially
   in the builtins and the ``collections`` and ``itertools`` modules). The
   Python Package Index also offers additional alternatives. Sometimes, the
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
@@ -37,11 +37,11 @@ Let's begin! 🚀
 2. In a separate browser tab or window, go to the ``Settings``
    tab of your target repository and then click on `Secrets`_
    in the left sidebar.
-3. Create a new secret called ``pypi_password`` and copy-paste
-   the token from the fist step.
+3. Create a new secret called ``PYPI_API_TOKEN`` and copy-paste
+   the token from the first step.
 4. Now, go to https://test.pypi.org/manage/account/#api-tokens
    and repeat the steps. Save that TestPyPI token on GitHub
-   as ``test_pypi_password``.
+   as ``TEST_PYPI_API_TOKEN``.
 
    .. attention::
 
@@ -87,13 +87,13 @@ Then, add the following under the ``build-n-publish`` section:
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
    :start-after: runs-on:
-   :end-before: Install pep517
+   :end-before: Install pypa/build
 
 This will download your repository into the CI runner and then
 install and activate Python 3.7.
 
 And now we can build dists from source. In this example, we'll
-use ``pep517`` package, assuming that your project has a
+use ``build`` package, assuming that your project has a
 ``pyproject.toml`` properly set up (see
 :pep:`517`/:pep:`518`).
 
diff --git a/source/key_projects.rst b/source/key_projects.rst
@@ -31,6 +31,22 @@ context of automated tests) and to prevent heavily loading PyPI's
 Content Delivery Network (CDN).
 
 
+.. _build:
+
+build
+=====
+
+`Docs <https://pypa-build.readthedocs.io/>`__ |
+`Issues <https://github.com/pypa/build/issues>`__ |
+`GitHub <https://github.com/pypa/build>`__ |
+`PyPI <https://pypi.org/project/build>`__ |
+User IRC:`#pypa <https://webchat.freenode.net/?channels=%23pypa>`__ |
+Dev IRC:`#pypa-dev <https://webchat.freenode.net/?channels=%23pypa-dev>`__
+
+``build`` is a PEP-517 compatible Python package builder. It provides a CLI to
+build packages, as well as a Python API.
+
+
 .. _distlib:
 
 distlib
@@ -531,11 +547,10 @@ poetry
 
 poetry is a command-line tool to handle dependency installation and
 isolation as well as building and packaging of Python packages. It
-uses ``pyproject.toml`` and provides its own dependency resolver, and,
-instead of depending on the resolver functionality within :ref:`pip`,
-provides its own dependency resolver. It attempts to speed users'
-experience of installation and dependency resolution by locally
-caching metadata about dependencies.
+uses ``pyproject.toml`` and, instead of depending on the resolver
+functionality within :ref:`pip`, provides its own dependency resolver.
+It attempts to speed users' experience of installation and dependency
+resolution by locally caching metadata about dependencies.
 
 .. _pypiserver:
 
diff --git a/source/overview.rst b/source/overview.rst
@@ -167,7 +167,7 @@ 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
-<http://setuptools.readthedocs.io/en/latest/setuptools.html#automatic-script-creation>`_.
+<https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html>`_.
 
 Libraries are building blocks, not complete applications. For
 distributing applications, there's a whole new world of technologies
@@ -308,14 +308,14 @@ program into one of these formats, most of which involve embedding the
 Python interpreter and any other dependencies into a single executable
 file.
 
-This approach, called *freezing*, offers wide compatiblity and
+This approach, called *freezing*, offers wide compatibility and
 seamless user experience, though often requires multiple technologies,
 and a good amount of effort.
 
 A selection of Python freezers:
 
 * `pyInstaller <http://www.pyinstaller.org/>`_ - Cross-platform
-* `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ - Cross-platform
+* `cx_Freeze <https://marcelotduarte.github.io/cx_Freeze/>`_ - Cross-platform
 * `constructor <https://github.com/conda/constructor>`_ - For command-line installers
 * `py2exe <http://www.py2exe.org/>`_ - Windows only
 * `py2app <https://py2app.readthedocs.io/en/latest/>`_ - Mac only
@@ -416,7 +416,7 @@ virtualenv
 
 `Virtualenvs
 <http://python-guide.readthedocs.io/en/latest/dev/virtualenvs/>`_ have
-been an indispensible tool for multiple generations of Python
+been an indispensable tool for multiple generations of Python
 developer, but are slowly fading from view, as they are being wrapped
 by higher-level tools. With packaging in particular, virtualenvs are
 used as a primitive in `the dh-virtualenv tool
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
diff --git a/source/specifications/entry-points.rst b/source/specifications/entry-points.rst
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst

Original file line number	Diff line number	Diff line change
`@@ -196,8 +196,8 @@`
`196`	`196`
`197`	`197`	`# Custom sidebar templates, filenames relative to this file.`
`198`	`198`	`html_sidebars = {`
`199`		`- '**': ['localtoc.html', 'relations.html'],`
`200`		`- 'index': ['localtoc.html']`
	`199`	`+ '**': ['globaltoc.html', 'relations.html'],`
	`200`	`+ 'index': ['globaltoc.html']`
`201`	`201`	`}`
`202`	`202`
`203`	`203`	`# Additional templates that should be rendered to pages, maps page names to`