Apply suggestions from code review

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: woodruffw

peps/pep-0807.rst

@@ -7,7 +7,7 @@ Status: Draft
 Type: Standards Track
 Topic: Packaging
 Created: 15-Sep-2025
-Post-History: `08-Aug-2025 <https://discuss.python.org/t/pre-pep-trusted-publishing-token-exchange/103067>`__
+Post-History: `08-Aug-2025 <https://discuss.python.org/t/103067>`__,
 
 Abstract
 ========
@@ -35,7 +35,7 @@ to the index.
 
 Trusted Publishing was originally designed and enabled on PyPI in 2023 as
 a non-standard (PyPI-specific) feature, much like the existing
-`upload API <https://docs.pypi.org/trusted-publishers/>`_. It has seen
+`upload API <https://docs.pypi.org/api/upload/>`__. It has seen
 widespread adoption in that capacity: over 640,000 files have been published
 to PyPI using a Trusted Publisher (as of September 2025), and PyPI's
 design has inspired similar designs in the
@@ -63,16 +63,15 @@ This PEP's specification contains two parts:
 * A *token exchange* mechanism that package upload clients can use to
   exchange an identity credential for an upload credential.
 
-.. _constraints:
 
 Constraints
 -----------
 
 Unless explicitly stated otherwise, the following constraints
 apply to all parts of this PEP's specification:
 
-* All URLs **MUST** have
-  `potentially trustworthy origins <https://www.w3.org/TR/secure-contexts/#potentially-trustworthy-origins>`_.
+* All URLs **MUST** have `potentially trustworthy origins
+  <https://www.w3.org/TR/secure-contexts/#potentially-trustworthy-origins>`__.
   In practice, this means that all URLs **MUST** use the ``https``
   scheme, be some variant of a local loopback (``localhost``,
   ``127.0.0.1``, etc.), or otherwise be considered *a priori* trustworthy
@@ -96,13 +95,12 @@ apply to all parts of this PEP's specification:
   Receiving servers **SHOULD** respond with a ``406 Not Acceptable``
   status code if any other ``Accept`` header is present.
 
-.. _discovery:
 
 Trusted Publishing Discovery
 ----------------------------
 
 All Python package uploading is currently "endpoint driven," in the sense
-uploading clients (like twine and uv) are given an upload URL (and
+uploading clients (like *twine* and *uv*) are given an upload URL (and
 **not** merely a domain name).
 
 For example, to upload to PyPI, uploading clients are expected to connect
@@ -154,10 +152,10 @@ The discovery mechanism is as follows:
 
    .. code-block:: json
 
-       {
-            "audience-endpoint": "https://upload.example.com/_/oidc/audience",
-            "token-mint-endpoint": "https://upload.example.com/_/oidc/mint-token"
-       }
+      {
+         "audience-endpoint": "https://upload.example.com/_/oidc/audience",
+         "token-mint-endpoint": "https://upload.example.com/_/oidc/mint-token"
+      }
 
 If the server does not support Trusted Publishing for the given
 upload URL, it **MUST** respond with a ``404 Not Found`` status code.
@@ -170,7 +168,7 @@ error code in the 400 or 500 range to indicate an error condition.
 
 Non-``200 OK``, non-``404 Not Found`` responses **MAY** include a body which,
 if present, **MUST** be a JSON object containing an
-:ref:`Error Response <error-responses>`.
+`Error Response`_.
 
 .. _token-exchange:
 
@@ -229,7 +227,7 @@ an HTTP POST request to the *mint token endpoint* obtained during
 :ref:`discovery <discovery>`.
 
 On success, the server responds with a ``200 OK`` status code and a body
-containing a JSON object with the following field:
+containing a JSON object with the following fields:
 
 - ``token``: a string containing the upload credential. The format
   of the upload credential is implementation-defined and index-specific.
@@ -314,8 +312,10 @@ has been accompanied by a variety of educational resources on
 adopting Trusted Publishing as an end user, including:
 
 * Python Packaging User Guide: :ref:`packaging:trusted-publishing`
-* PyPI: `Publishing to PyPI with a Trusted Publisher <https://docs.pypi.org/trusted-publishers/>`_
-* pyOpenSci: `Setup Trusted Publishing for secure and automated publishing via GitHub Actions <https://www.pyopensci.org/python-package-guide/tutorials/trusted-publishing.html>`_
+* PyPI: `Publishing to PyPI with a Trusted Publisher
+  <https://docs.pypi.org/trusted-publishers/>`__
+* pyOpenSci: `Setup Trusted Publishing for secure and automated publishing via GitHub Actions
+  <https://www.pyopensci.org/python-package-guide/tutorials/trusted-publishing.html>`__
 
 Rejected Ideas
 ==============
@@ -325,8 +325,8 @@ Rejected Ideas
 
 This PEP's discovery mechanism uses the ``.well-known`` location scheme
 defined in :rfc:`8615`. This scheme is widely adopted by machine-to-machine
-protocols, including OpenID Connect itself
-(for `OpenID Connect Discovery <https://openid.net/specs/openid-connect-discovery-1_0.html>`_).
+protocols, including OpenID Connect itself (for `OpenID Connect Discovery
+<https://openid.net/specs/openid-connect-discovery-1_0.html>`__).
 
 An alternative idea considered was to use a "lateral" discovery mechanism,
 in which the uploading client would attempt discovery by constructing a
@@ -377,7 +377,9 @@ This approach too has downsides:
   the audience and mint token endpoints, which means significant disruption
   to existing clients if those endpoints ever need to change.
 
-.. rubric:: Footnotes
+
+Footnotes
+=========
 
 .. [#fn-hash] ``shasum -a 256 <<< '/legacy/'``