Merge branch 'main' into distributing-guide

Author: jeanas

source/guides/dropping-older-python-versions.rst

@@ -78,7 +78,9 @@ Steps:
 
 You can specify version ranges and exclusion rules, such as at least Python 3. Or, Python 2.7, 3.4 and beyond.
 
-Examples::
+Examples:
+
+.. code-block:: text
 
     Requires-Python: ">=3"
     Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"

source/guides/installing-using-linux-tools.rst

@@ -107,9 +107,9 @@ To install pip, wheel, and setuptools, in a parallel, non-system environment
 openSUSE
 ~~~~~~~~
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    sudo zypper install python3-pip python3-setuptools python3-wheel
+   sudo zypper install python3-pip python3-setuptools python3-wheel
 
 
 .. _debian-ubuntu:
@@ -134,9 +134,9 @@ Firstly, update and refresh repository lists by running this command:
 Arch Linux
 ~~~~~~~~~~
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    sudo pacman -S python-pip
+   sudo pacman -S python-pip
 
 ----
 

source/guides/making-a-pypi-friendly-readme.rst

@@ -59,9 +59,9 @@ such as ``text/plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdow
 
    The minimum required versions of the respective tools are:
 
-    - ``setuptools >= 38.6.0``
-    - ``wheel >= 0.31.0``
-    - ``twine >= 1.11.0``
+   - ``setuptools >= 38.6.0``
+   - ``wheel >= 0.31.0``
+   - ``twine >= 1.11.0``
 
    It's recommended that you use ``twine`` to upload the project's distribution packages:
 

source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst

@@ -37,13 +37,13 @@ for your new :term:`PyPI project <Project>`.
 However it is also possible to add `trusted publishing`_ to any
 pre-existing project, if you are its owner.
 
-   .. attention::
+.. attention::
 
-      If you followed earlier versions of this guide, you
-      have created the secrets ``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN``
-      for direct PyPI and TestPyPI access. These are obsolete now and
-      you should remove them from your GitHub repository and revoke
-      them in your PyPI and TestPyPI account settings in case you are replacing your old setup with the new one.
+   If you followed earlier versions of this guide, you
+   have created the secrets ``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN``
+   for direct PyPI and TestPyPI access. These are obsolete now and
+   you should remove them from your GitHub repository and revoke
+   them in your PyPI and TestPyPI account settings in case you are replacing your old setup with the new one.
 
 
 Let's begin! 🚀

source/guides/using-testpypi.rst

@@ -75,7 +75,7 @@ Setting up TestPyPI in :file:`.pypirc`
 If you want to avoid entering your username, you can configure TestPyPI in
 your :file:`$HOME/.pypirc`:
 
-.. code::
+.. code:: ini
 
     [testpypi]
     username = <your TestPyPI username>

source/specifications/binary-distribution-format.rst

@@ -1,18 +1,13 @@
+.. highlight:: text
 
 .. _binary-distribution-format:
 
 ==========================
 Binary distribution format
 ==========================
 
-The binary distribution format (:term:`wheel <Wheel>`) was originally defined
-in :pep:`427`. The current version of the specification is here.
-
-
-Abstract
-========
-
-This PEP describes a built-package format for Python called "wheel".
+This page specifies the binary distribution format for Python packages,
+also called the wheel format.
 
 A wheel is a ZIP-format archive with a specially formatted file name and
 the ``.whl`` extension.  It contains a single distribution nearly as it
@@ -23,31 +18,6 @@ may be installed by simply unpacking into site-packages with the standard
 out onto their final paths at any later time.
 
 
-PEP Acceptance
-==============
-
-This PEP was accepted, and the defined wheel version updated to 1.0, by
-Nick Coghlan on 16th February, 2013 [1]_
-
-
-Rationale
-=========
-
-Python needs a package format that is easier to install than sdist.
-Python's sdist packages are defined by and require the distutils and
-setuptools build systems, running arbitrary code to build-and-install,
-and re-compile, code just so it can be installed into a new
-virtualenv.  This system of conflating build-install is slow, hard to
-maintain, and hinders innovation in both build systems and installers.
-
-Wheel attempts to remedy these problems by providing a simpler
-interface between the build system and the installer.  The wheel
-binary package format frees installers from having to know about the
-build system, saves time by amortizing compile time over many
-installations, and removes the need to install a build system in the
-target environment.
-
-
 Details
 =======
 
@@ -316,7 +286,9 @@ or the installation will fail.
 If JSON web signatures are used, one or more JSON Web Signature JSON
 Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent
 to RECORD.  JWS is used to sign RECORD by including the SHA-256 hash of
-RECORD as the signature's JSON payload::
+RECORD as the signature's JSON payload:
+
+.. code-block:: json
 
     { "hash": "sha256=ADD-r2urObZHcxBW3Cr-vDCu5RJwT4CaRTHiFmbcIYY" }
 
@@ -338,33 +310,6 @@ See
 - https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01
 
 
-Comparison to .egg
-------------------
-
-#. Wheel is an installation format; egg is importable.  Wheel archives
-   do not need to include .pyc and are less tied to a specific Python
-   version or implementation. Wheel can install (pure Python) packages
-   built with previous versions of Python so you don't always have to
-   wait for the packager to catch up.
-#. Wheel uses .dist-info directories; egg uses .egg-info.  Wheel is
-   compatible with the new world of Python packaging and the new
-   concepts it brings.
-#. Wheel has a richer file naming convention for today's
-   multi-implementation world.  A single wheel archive can indicate
-   its compatibility with a number of Python language versions and
-   implementations, ABIs, and system architectures.  Historically the
-   ABI has been specific to a CPython release, wheel is ready for the
-   stable ABI.
-#. Wheel is lossless.  The first wheel implementation bdist_wheel
-   always generates egg-info, and then converts it to a .whl.  It is
-   also possible to convert existing eggs and bdist_wininst
-   distributions.
-#. Wheel is versioned.  Every wheel file contains the version of the
-   wheel specification and the implementation that packaged it.
-   Hopefully the next migration can simply be to Wheel 2.0.
-#. Wheel is a reference to the other Python.
-
-
 FAQ
 ===
 
@@ -469,20 +414,16 @@ Is it possible to import Python code directly from a wheel file?
     aware that many projects will require a failure to be reproduced with
     a fully installed package before accepting it as a genuine bug.
 
-Changes
-=======
 
-Since :pep:`427`, this specification has changed as follows:
-
-- The rules on escaping in wheel filenames were revised, to bring them into line
-  with what popular tools actually do (February 2021).
+History
+=======
 
+This specification was originally approved as :pep:`427`.
 
-References
-==========
+The following changes were applied since the initial version:
 
-.. [1] PEP acceptance
-   (https://mail.python.org/pipermail/python-dev/2013-February/124103.html)
+- The rules on escaping in wheel filenames were revised, to bring them
+  into line with what popular tools actually do (February 2021).
 
 
 Appendix
@@ -499,9 +440,3 @@ Example urlsafe-base64-nopad implementation::
     def urlsafe_b64decode_nopad(data):
         pad = b'=' * (4 - (len(data) & 3))
         return base64.urlsafe_b64decode(data + pad)
-
-
-Copyright
-=========
-
-This document has been placed into the public domain.

source/specifications/core-metadata.rst

@@ -1,3 +1,5 @@
+.. highlight:: text
+
 .. _`core-metadata`:
 
 ============================

source/specifications/dependency-specifiers.rst

@@ -1,3 +1,5 @@
+.. highlight:: text
+
 .. _dependency-specifiers:
 
 =====================
@@ -273,7 +275,9 @@ error like all other unknown variables.
      - ``test``
 
 The ``implementation_version`` marker variable is derived from
-``sys.implementation.version``::
+``sys.implementation.version``:
+
+.. code-block:: python
 
     def format_full_version(info):
         version = '{0.major}.{0.minor}.{0.micro}'.format(info)
@@ -400,7 +404,9 @@ The complete parsley grammar::
     sub_delims    = '!' | '$' | '&' | '\\'' | '(' | ')' | '*' | '+' | ',' | ';' | '='
     hexdig        = digit | 'a' | 'A' | 'b' | 'B' | 'c' | 'C' | 'd' | 'D' | 'e' | 'E' | 'f' | 'F'
 
-A test program - if the grammar is in a string ``grammar``::
+A test program - if the grammar is in a string ``grammar``:
+
+.. code-block:: python
 
     import os
     import sys

source/specifications/direct-url-data-structure.rst

@@ -1,3 +1,4 @@
+.. highlight:: json
 
 .. _direct-url-data-structure:
 
@@ -32,7 +33,9 @@ for security reasons.
 
 The user:password section of the URL MAY however
 be composed of environment variables, matching the following regular
-expression::
+expression:
+
+.. code-block:: text
 
     \$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?
 
@@ -130,24 +133,19 @@ Git
 ---
 
 Home page
-
    https://git-scm.com/
 
 vcs command
-
    git
 
 ``vcs`` field
-
    git
 
 ``requested_revision`` field
-
    A tag name, branch name, Git ref, commit hash, shortened commit hash,
    or other commit-ish.
 
 ``commit_id`` field
-
    A commit hash (40 hexadecimal characters sha1).
 
 .. note::
@@ -162,70 +160,55 @@ Mercurial
 ---------
 
 Home page
-
    https://www.mercurial-scm.org/
 
 vcs command
-
    hg
 
 ``vcs`` field
-
    hg
 
 ``requested_revision`` field
-
    A tag name, branch name, changeset ID, shortened changeset ID.
 
 ``commit_id`` field
-
    A changeset ID (40 hexadecimal characters).
 
 Bazaar
 ------
 
 Home page
-
    https://www.breezy-vcs.org/
 
 vcs command
-
    bzr
 
 ``vcs`` field
-
    bzr
 
 ``requested_revision`` field
-
    A tag name, branch name, revision id.
 
 ``commit_id`` field
-
    A revision id.
 
 Subversion
 ----------
 
 Home page
-
    https://subversion.apache.org/
 
 vcs command
-
    svn
 
 ``vcs`` field
-
    svn
 
 ``requested_revision`` field
-
    ``requested_revision`` must be compatible with ``svn checkout`` ``--revision`` option.
    In Subversion, branch or tag is part of ``url``.
 
 ``commit_id`` field
-
    Since Subversion does not support globally unique identifiers,
    this field is the Subversion revision number in the corresponding
    repository.

source/specifications/entry-points.rst

@@ -111,7 +111,9 @@ restrictions on values specified in :pep:`685`.
 For tools writing the file, it is recommended only to insert a space between the
 object reference and the left square bracket.
 
-For example::
+For example:
+
+.. code-block:: ini
 
     [console_scripts]
     foo = foomod:main