Merge branch 'main' into pep-695

.github/CODEOWNERS

@@ -576,6 +576,7 @@ pep-0692.rst  @jellezijlstra
 pep-0693.rst  @Yhg1s
 pep-0694.rst  @dstufft
 pep-0695.rst  @gvanrossum
+pep-0696.rst  @jellezijlstra
 # ...
 # pep-0754.txt
 # ...

.github/workflows/lint.yml

@@ -12,9 +12,9 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Set up Python 3
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: '3.x'
 
       - name: Run pre-commit hooks
-        uses: pre-commit/action@v2.0.3
+        uses: pre-commit/action@v3.0.0

.github/workflows/render.yml

@@ -6,36 +6,39 @@ jobs:
   render-peps:
     name: Render PEPs
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.x", "3.11-dev"]
 
     steps:
       - name: 🛎️ Checkout
         uses: actions/checkout@v3
         with:
           fetch-depth: 0  # fetch all history so that last modified date-times are accurate
 
-      - name: 🐍 Set up Python 3
-        uses: actions/setup-python@v3
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
         with:
-          python-version: '3.x'
-          cache: "pip"
+          python-version: ${{ matrix.python-version }}
+          cache: pip
 
       - name: 👷‍ Install dependencies
         run: |
           python -m pip install --upgrade pip
 
       - name: 🔧 Render PEPs
-        run: make pages -j$(nproc)
+        run: make pages JOBS=$(nproc)
 
         # remove the .doctrees folder when building for deployment as it takes two thirds of disk space
       - name: 🔥 Clean up files
         run: rm -r build/.doctrees/
 
       - name: 🚀 Deploy to GitHub pages
         # This allows CI to build branches for testing
-        if: github.ref == 'refs/heads/main'
-        uses: JamesIves/github-pages-deploy-action@v4.2.2
+        if: (github.ref == 'refs/heads/main') && (matrix.python-version == '3.x')
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          branch: gh-pages # The branch to deploy to.
           folder: build # Synchronise with build.py -> build_directory
           single-commit: true # Delete existing files
 

.github/workflows/test.yml

@@ -22,14 +22,17 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10"]
+        python-version: ["3.9", "3.10", "3.11-dev"]
         os: [windows-latest, macos-latest, ubuntu-latest]
+        # lxml doesn't yet install for 3.11 on Windows
+        exclude:
+        - { python-version: "3.11-dev", os: windows-latest }
 
     steps:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip

.gitignore

@@ -1,3 +1,4 @@
+coverage.xml
 pep-0000.txt
 pep-0000.rst
 pep-????.html

Makefile

@@ -3,7 +3,8 @@
 PYTHON=python3
 VENVDIR=.venv
 JOBS=8
-RENDER_COMMAND=$(VENVDIR)/bin/python3 build.py -j $(JOBS)
+OUTPUT_DIR=build
+RENDER_COMMAND=$(VENVDIR)/bin/python3 build.py -j $(JOBS) -o $(OUTPUT_DIR)
 
 render: venv
 	$(RENDER_COMMAND)

build.py

@@ -36,6 +36,12 @@ def create_parser():
     parser.add_argument("-j", "--jobs", type=int, default=1,
                         help="How many parallel jobs to run (if supported). "
                              "Integer, default 1.")
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        default="build",  # synchronise with render.yaml -> deploy step
+        help="Output directory, relative to root. Default 'build'.",
+    )
 
     return parser.parse_args()
 
@@ -57,7 +63,7 @@ def create_index_file(html_root: Path, builder: str) -> None:
 
     root_directory = Path(".").absolute()
     source_directory = root_directory
-    build_directory = root_directory / "build"  # synchronise with deploy-gh-pages.yaml -> deploy step
+    build_directory = root_directory / args.output_dir
     doctree_directory = build_directory / ".doctrees"
 
     # builder configuration

conf.py

@@ -10,7 +10,7 @@
 
 # Add 'include_patterns' as a config variable
 from sphinx.config import Config
-Config.config_values['include_patterns'] = [], 'env', []
+Config.config_values["include_patterns"] = [], "env", []
 del Config
 
 # -- Project information -----------------------------------------------------
@@ -21,7 +21,11 @@
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings.
-extensions = ["pep_sphinx_extensions", "sphinx.ext.githubpages"]
+extensions = [
+"pep_sphinx_extensions",
+"sphinx.ext.intersphinx",
+"sphinx.ext.githubpages",
+]
 
 # The file extensions of source files. Sphinx uses these suffixes as sources.
 source_suffix = {
@@ -46,6 +50,13 @@
     "pep-0012/pep-NNNN.rst",
 ]
 
+# Intersphinx configuration
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'packaging': ('https://packaging.python.org/en/latest/', None),
+}
+intersphinx_disabled_reftypes = []
+
 # -- Options for HTML output -------------------------------------------------
 
 # HTML output settings
@@ -60,4 +71,4 @@
 html_baseurl = "https://peps.python.org"  # to create the CNAME file
 gettext_auto_build = False  # speed-ups
 
-templates_path = ['pep_sphinx_extensions/pep_theme/templates']  # Theme template relative paths from `confdir`
+templates_path = ["pep_sphinx_extensions/pep_theme/templates"]  # Theme template relative paths from `confdir`

generate_rss.py

@@ -7,8 +7,7 @@
 from pathlib import Path
 import re
 
-import docutils
-from docutils import frontend
+import docutils.frontend
 from docutils import nodes
 from docutils import utils
 from docutils.parsers import rst
@@ -25,14 +24,6 @@ def _format_rfc_2822(dt: datetime.datetime) -> str:
     return email.utils.format_datetime(dt, usegmt=True)
 
 
-# Monkeypatch nodes.Node.findall for forwards compatability
-if docutils.__version_info__ < (0, 18, 1):
-    def findall(self, *args, **kwargs):
-        return iter(self.traverse(*args, **kwargs))
-
-    nodes.Node.findall = findall
-
-
 entry.formatRFC2822 = feed.formatRFC2822 = _format_rfc_2822
 line_cache: dict[Path, dict[str, str]] = {}
 
@@ -131,7 +122,7 @@ def pep_creation(full_path: Path) -> datetime.datetime:
 
 def parse_rst(full_path: Path) -> nodes.document:
     text = full_path.read_text(encoding="utf-8")
-    settings = frontend.OptionParser((rst.Parser,)).get_default_values()
+    settings = docutils.frontend.get_default_settings(rst.Parser)
     document = utils.new_document(f'<{full_path}>', settings=settings)
     rst.Parser(rfc2822=True).parse(text, document)
     return document

pep-0012.rst

@@ -649,6 +649,66 @@ If you find that you need to use a backslash in your text, consider
 using inline literals or a literal block instead.
 
 
+Canonical Documentation and Intersphinx
+---------------------------------------
+
+As :pep:`PEP 1 describes <1#pep-maintenance>`,
+PEPs are considered historical documents once marked Final,
+and their canonical documentation/specification should be moved elsewhere.
+To indicate this, use the ``canonical-docs`` directive
+or an appropriate subclass
+(currently ``canonical-pypa-spec`` for packaging standards).
+
+Furthermore, you can use
+`Intersphinx references
+<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
+to other Sphinx sites,
+currently the `Python documentation <https://docs.python.org/>`_
+and `packaging.python.org <https://packaging.python.org/>`_,
+to easily cross-reference pages, sections and Python/C objects.
+This works with both the "canonical" directives and anywhere in your PEP.
+
+Add the directive between the headers and the first section of the PEP
+(typically the Abstract)
+and pass as an argument an Intersphinx reference of the canonical doc/spec
+(or if the target is not on a Sphinx site, a `reST hyperlink <Hyperlinks_>`__).
+
+For example,
+to create a banner pointing to the :mod:`python:sqlite3` docs,
+you would write the following::
+
+    .. canonical-doc:: :mod:`python:sqlite3`
+
+which would generate the banner:
+
+    .. canonical-doc:: :mod:`python:sqlite3`
+
+Or for a PyPA spec,
+such as the :ref:`packaging:core-metadata`,
+you would use::
+
+    .. canonical-pypa-spec:: :ref:`packaging:core-metadata`
+
+which renders as:
+
+    .. canonical-pypa-spec:: :ref:`packaging:core-metadata`
+
+The argument accepts arbitrary reST,
+so you can include multiple linked docs/specs and name them whatever you like,
+and you can also include directive content that will be inserted into the text.
+The following advanced example::
+
+    .. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
+
+        Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
+
+would render as:
+
+    .. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:sqlite3.DataError` docs
+
+        Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
+
+
 Habits to Avoid
 ===============
 

pep-0229.txt

@@ -7,6 +7,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 16-Nov-2000
+Python-Version: 2.1
 Post-History:
 
 

pep-0282.txt

@@ -64,7 +64,7 @@ Simple Example
 This shows a very simple example of how the logging package can be
 used to generate simple logging output on stderr.
 
-::
+.. code-block:: python
 
     --------- mymodule.py -------------------------------
     import logging
@@ -76,6 +76,8 @@ used to generate simple logging output on stderr.
             raise TypeError, "Bogus type error for testing"
     -----------------------------------------------------
 
+.. code-block:: python 
+
     --------- myapp.py ----------------------------------
     import mymodule, logging
 
@@ -91,7 +93,9 @@ used to generate simple logging output on stderr.
     log.info("Ending my app")
     -----------------------------------------------------
 
-    % python myapp.py
+.. code-block:: console 
+
+    $ python myapp.py
 
     INFO:MyApp: Starting my app
     DEBUG:MyModule: Doin' stuff...
@@ -107,7 +111,9 @@ used to generate simple logging output on stderr.
 
 The above example shows the default output format.  All
 aspects of the output format should be configurable, so that
-you could have output formatted like this::
+you could have output formatted like this:
+
+.. code-block:: text 
 
     2002-04-19 07:56:58,174 MyModule   DEBUG - Doin' stuff...
 
@@ -127,11 +133,9 @@ Logger names fit into a "dotted name" namespace, with dots
 (periods) indicating sub-namespaces.  The namespace of logger
 objects therefore corresponds to a single tree data structure.
 
-::
-
-   "" is the root of the namespace
-   "Zope" would be a child node of the root
-   "Zope.ZODB" would be a child node of "Zope"
+* ``""`` is the root of the namespace
+* ``"Zope"`` would be a child node of the root
+* ``"Zope.ZODB"`` would be a child node of ``"Zope"``
 
 These Logger objects create **LogRecord** objects which are passed
 to **Handler** objects for output.  Both Loggers and Handlers may
@@ -170,13 +174,13 @@ This is done through a module-level function::
 Levels
 ======
 
-The logging levels, in increasing order of importance, are::
+The logging levels, in increasing order of importance, are:
 
-    DEBUG
-    INFO
-    WARN
-    ERROR
-    CRITICAL
+* DEBUG
+* INFO
+* WARN
+* ERROR
+* CRITICAL
 
 The term CRITICAL is used in preference to FATAL, which is used by
 log4j.  The levels are conceptually the same - that of a serious,

pep-0305.txt

@@ -12,6 +12,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 26-Jan-2003
+Python-Version: 2.3
 Post-History: 31-Jan-2003, 13-Feb-2003
 
 

pep-0307.txt

@@ -7,6 +7,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 31-Jan-2003
+Python-Version: 2.3
 Post-History: 07-Feb-2003
 
 Introduction

pep-0308.txt

@@ -7,6 +7,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 07-Feb-2003
+Python-Version: 2.5
 Post-History: 07-Feb-2003, 11-Feb-2003
 
 

pep-0311.txt

@@ -7,6 +7,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 05-Feb-2003
+Python-Version: 2.3
 Post-History: 05-Feb-2003, 14-Feb-2003, 19-Apr-2003
 
 

pep-0341.txt

@@ -7,6 +7,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 04-May-2005
+Python-Version: 2.5
 Post-History:
 
 

pep-0352.txt

@@ -7,6 +7,7 @@ Status: Final
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 27-Oct-2005
+Python-Version: 2.5
 Post-History: