Merge branch 'main' into patch-2

Author: pradyunsg

source/guides/distributing-packages-using-setuptools.rst

@@ -773,7 +773,7 @@ If your project is pure Python then you'll be creating a
 If your project contains compiled extensions, then you'll be creating what's
 called a :ref:`*Platform Wheel* (see section below) <Platform Wheels>`.
 
-.. note:: If your project also supports Python 2 _and_ contains no C extensions,
+.. note:: If your project also supports Python 2 *and* contains no C extensions,
   then you should create what's called a *Universal Wheel* by adding the
   following to your :file:`setup.cfg` file:
 
@@ -782,7 +782,7 @@ called a :ref:`*Platform Wheel* (see section below) <Platform Wheels>`.
      [bdist_wheel]
      universal=1
 
-  Only use this setting if your project does not have any C extesions _and_
+  Only use this setting if your project does not have any C extensions *and*
   supports Python 2 and 3.
 
 

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/installing-using-pip-and-virtual-environments.rst

@@ -19,46 +19,43 @@ update packages. You'll need to make sure you have the latest version of pip
 installed.
 
 
-Windows
-+++++++
-
-The Python installers for Windows include pip. You should be able to access
-pip using:
+.. tab:: Unix/macOS
 
-.. code-block:: bash
+    Debian and most other distributions include a `python-pip`_ package, if you
+    want to use the Linux distribution-provided versions of pip see
+    :doc:`/guides/installing-using-linux-tools`.
 
-    py -m pip --version
-    pip 9.0.1 from c:\python36\lib\site-packages (Python 3.6.1)
+    You can also install pip yourself to ensure you have the latest version. It's
+    recommended to use the system pip to bootstrap a user installation of pip:
 
-You can make sure that pip is up-to-date by running:
+    .. code-block:: bash
 
-.. code-block:: bash
+        python3 -m pip install --user --upgrade pip
 
-    py -m pip install --upgrade pip
+    Afterwards, you should have the newest pip installed in your user site:
 
+    .. code-block:: bash
 
-Linux and macOS
-++++++++++++++++
+        python3 -m pip --version
+        pip 9.0.1 from $HOME/.local/lib/python3.6/site-packages (python 3.6)
 
-Debian and most other distributions include a `python-pip`_ package, if you
-want to use the Linux distribution-provided versions of pip see
-:doc:`/guides/installing-using-linux-tools`.
+    .. _python-pip: https://packages.debian.org/stable/python-pip
 
-You can also install pip yourself to ensure you have the latest version. It's
-recommended to use the system pip to bootstrap a user installation of pip:
+.. tab:: Windows
 
-.. code-block:: bash
+    The Python installers for Windows include pip. You should be able to access
+    pip using:
 
-    python3 -m pip install --user --upgrade pip
+    .. code-block:: bash
 
-Afterwards, you should have the newest pip installed in your user site:
+        py -m pip --version
+        pip 9.0.1 from c:\python36\lib\site-packages (Python 3.6.1)
 
-.. code-block:: bash
+    You can make sure that pip is up-to-date by running:
 
-    python3 -m pip --version
-    pip 9.0.1 from $HOME/.local/lib/python3.6/site-packages (python 3.6)
+    .. code-block:: bash
 
-.. _python-pip: https://packages.debian.org/stable/python-pip
+        py -m pip install --upgrade pip
 
 
 Installing virtualenv
@@ -75,17 +72,18 @@ Using virtualenv allows you to avoid installing Python packages globally
 which could break system tools or other projects. You can install virtualenv
 using pip.
 
-On macOS and Linux:
 
-.. code-block:: bash
+.. tab:: Unix/macOS
 
-    python3 -m pip install --user virtualenv
+    .. code-block:: bash
 
-On Windows:
+        python3 -m pip install --user virtualenv
 
-.. code-block:: bash
+.. tab:: Windows
+
+    .. code-block:: bash
 
-    py -m pip install --user virtualenv
+        py -m pip install --user virtualenv
 
 
 
@@ -105,17 +103,17 @@ To create a virtual environment, go to your project's directory and run
 venv. If you are using Python 2, replace ``venv`` with ``virtualenv``
 in the below commands.
 
-On macOS and Linux:
+.. tab:: Unix/macOS
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    python3 -m venv env
+        python3 -m venv env
 
-On Windows:
+.. tab:: Windows
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    py -m venv env
+        py -m venv env
 
 The second argument is the location to create the virtual environment. Generally, you
 can just create this in your project and call it ``env``.
@@ -134,33 +132,34 @@ need to *activate* it. Activating a virtual environment will put the
 virtual environment-specific
 ``python`` and ``pip`` executables into your shell's ``PATH``.
 
-On macOS and Linux:
+.. tab:: Unix/macOS
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    source env/bin/activate
+        source env/bin/activate
 
-On Windows::
+.. tab:: Windows
+
+    .. code-block:: text
 
-    .\env\Scripts\activate
+        .\env\Scripts\activate
 
 You can confirm you're in the virtual environment by checking the location of your
 Python interpreter, it should point to the ``env`` directory.
 
-On macOS and Linux:
-
-.. code-block:: bash
+.. tab:: Unix/macOS
 
-    which python
-    .../env/bin/python
+    .. code-block:: bash
 
-On Windows:
+        which python
+        .../env/bin/python
 
-.. code-block:: bash
+.. tab:: Windows
 
-    where python
-    .../env/bin/python.exe
+    .. code-block:: text
 
+        where python
+        ...\env\Scripts\python.exe
 
 As long as your virtual environment is activated pip will install packages into that
 specific environment and you'll be able to import and use packages in your

source/guides/packaging-binary-extensions.rst

@@ -240,6 +240,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
 -----------------------------