Merge branch 'main' into tabify-pip-and-virtual-environments

Author: ichard26

source/guides/installing-stand-alone-command-line-tools.rst

@@ -4,21 +4,21 @@ Installing stand alone command line tools
 Many packages have command line entry points. Examples of this type of application are
 `mypy <https://github.com/python/mypy>`_,
 `flake8 <https://github.com/PyCQA/flake8>`_,
-`pipenv <https://github.com/pypa/pipenv>`_,and
+:ref:`pipenv`,and
 `black <https://github.com/ambv/black>`_.
 
 Usually you want to be able to access these from anywhere,
 but installing packages and their dependencies to the same global environment
 can cause version conflicts and break dependencies the operating system has
 on Python packages.
 
-`pipx <https://github.com/pipxproject/pipx>`_ solves this by creating a virtual
+:ref:`pipx` solves this by creating a virtual
 environment for each package, while also ensuring that package's applications
 are accessible through a directory that is on your ``$PATH``. This allows each
 package to be upgraded or uninstalled without causing conflicts with other
 packages, and allows you to safely run the program from anywhere.
 
-.. Note:: pipx only works with Python 3.6+.
+.. note:: pipx only works with Python 3.6+.
 
 ``pipx`` is installed with ``pip``:
 
@@ -110,4 +110,4 @@ To see the full list of commands ``pipx`` offers, run
   $ pipx --help
 
 You can learn more about ``pipx`` at its homepage,
-https://github.com/pipxproject/pipx.
+https://github.com/pypa/pipx.

source/guides/packaging-binary-extensions.rst

@@ -232,6 +232,18 @@ guide includes an introduction to writing a
 Building binary extensions
 ==========================
 
+Building extensions for multiple platforms
+------------------------------------------
+
+If you plan to distribute your extension, you should provide
+:term:`wheels <Wheel>` for all the platforms you intend to support. For most
+extensions, this is at least one package per Python version times the number of
+OS and architectures you support.  These are usually built on continuous
+integration (CI) systems. There are tools to help you build highly
+redistributable binaries from CI; these include :ref:`cibuildwheel` and
+:ref:`multibuild`.
+
+
 Binary extensions for Windows
 -----------------------------
 

source/key_projects.rst

@@ -55,9 +55,8 @@ cibuildwheel
 `Discussions <https://github.com/pypa/cibuildwheel/discussions>`__ |
 `Discord #cibuildwheel <https://discord.com/invite/pypa>`__
 
-``cibuildwheel`` is a package that builds wheels for all common platforms and
-Python versions on most CI systems.
-
+``cibuildwheel`` is a Python package that builds :term:`wheels <Wheel>` for all common
+platforms and Python versions on most CI systems. Also see :ref:`multibuild`.
 
 .. _distlib:
 
@@ -165,6 +164,18 @@ Pipfile
 application-centric alternative to :ref:`pip`'s lower-level
 :file:`requirements.txt` file.
 
+.. _pipx:
+
+pipx
+====
+
+`Docs <https://pypa.github.io/pipx/>`__ |
+`GitHub <https://github.com/pypa/pipx>`__ |
+`PyPI <https://pypi.org/project/pipx/>`__
+
+pipx is a tool to install and run Python command-line applications without
+causing dependency conflicts with other packages installed on the system.
+
 
 Python Packaging User Guide
 ===========================
@@ -458,6 +469,16 @@ dependencies for, and publish packages to PyPI. Under the hood, it
 uses :ref:`twine` to upload packages to PyPI, and :ref:`pip` to download and
 install packages.
 
+.. _multibuild:
+
+multibuild
+==========
+
+`GitHub <https://github.com/matthew-brett/multibuild>`__
+
+Multibuild is a set of CI scripts for building and testing Python :term:`wheels <Wheel>` for
+Linux, macOS, and (less flexibly) Windows. Also see :ref:`cibuildwheel`.
+
 .. _pex:
 
 pex
@@ -473,17 +494,6 @@ files, standalone Python environments in the spirit of :ref:`virtualenv`.
 ``#!/usr/bin/env python`` and special :file:`__main__.py`, and are designed to
 make deployment of Python applications as simple as ``cp``.
 
-.. _pipx:
-
-pipx
-====
-
-`Docs <https://pipxproject.github.io/pipx/>`__ |
-`GitHub <https://github.com/pipxproject/pipx>`__ |
-`PyPI <https://pypi.org/project/pipx/>`__
-
-pipx is a tool to safely install and run Python CLI applications globally.
-
 .. _pip-tools:
 
 pip-tools