Skip to content

Commit d6340e1

Browse files
authored
Merge branch 'main' into pep-695
2 parents 2fbe588 + 8207275 commit d6340e1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

69 files changed

+1600
-864
lines changed

.github/CODEOWNERS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -576,6 +576,7 @@ pep-0692.rst @jellezijlstra
576576
pep-0693.rst @Yhg1s
577577
pep-0694.rst @dstufft
578578
pep-0695.rst @gvanrossum
579+
pep-0696.rst @jellezijlstra
579580
# ...
580581
# pep-0754.txt
581582
# ...

.github/workflows/lint.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ jobs:
1212
uses: actions/checkout@v3
1313

1414
- name: Set up Python 3
15-
uses: actions/setup-python@v3
15+
uses: actions/setup-python@v4
1616
with:
1717
python-version: '3.x'
1818

1919
- name: Run pre-commit hooks
20-
uses: pre-commit/action@v2.0.3
20+
uses: pre-commit/action@v3.0.0

.github/workflows/render.yml

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,36 +6,39 @@ jobs:
66
render-peps:
77
name: Render PEPs
88
runs-on: ubuntu-latest
9+
strategy:
10+
fail-fast: false
11+
matrix:
12+
python-version: ["3.x", "3.11-dev"]
913

1014
steps:
1115
- name: 🛎️ Checkout
1216
uses: actions/checkout@v3
1317
with:
1418
fetch-depth: 0 # fetch all history so that last modified date-times are accurate
1519

16-
- name: 🐍 Set up Python 3
17-
uses: actions/setup-python@v3
20+
- name: 🐍 Set up Python ${{ matrix.python-version }}
21+
uses: actions/setup-python@v4
1822
with:
19-
python-version: '3.x'
20-
cache: "pip"
23+
python-version: ${{ matrix.python-version }}
24+
cache: pip
2125

2226
- name: 👷‍ Install dependencies
2327
run: |
2428
python -m pip install --upgrade pip
2529
2630
- name: 🔧 Render PEPs
27-
run: make pages -j$(nproc)
31+
run: make pages JOBS=$(nproc)
2832

2933
# remove the .doctrees folder when building for deployment as it takes two thirds of disk space
3034
- name: 🔥 Clean up files
3135
run: rm -r build/.doctrees/
3236

3337
- name: 🚀 Deploy to GitHub pages
3438
# This allows CI to build branches for testing
35-
if: github.ref == 'refs/heads/main'
36-
uses: JamesIves/github-pages-deploy-action@v4.2.2
39+
if: (github.ref == 'refs/heads/main') && (matrix.python-version == '3.x')
40+
uses: JamesIves/github-pages-deploy-action@v4
3741
with:
38-
branch: gh-pages # The branch to deploy to.
3942
folder: build # Synchronise with build.py -> build_directory
4043
single-commit: true # Delete existing files
4144

.github/workflows/test.yml

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,17 @@ jobs:
2222
strategy:
2323
fail-fast: false
2424
matrix:
25-
python-version: ["3.9", "3.10"]
25+
python-version: ["3.9", "3.10", "3.11-dev"]
2626
os: [windows-latest, macos-latest, ubuntu-latest]
27+
# lxml doesn't yet install for 3.11 on Windows
28+
exclude:
29+
- { python-version: "3.11-dev", os: windows-latest }
2730

2831
steps:
2932
- uses: actions/checkout@v3
3033

3134
- name: Set up Python ${{ matrix.python-version }}
32-
uses: actions/setup-python@v3
35+
uses: actions/setup-python@v4
3336
with:
3437
python-version: ${{ matrix.python-version }}
3538
cache: pip

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
coverage.xml
12
pep-0000.txt
23
pep-0000.rst
34
pep-????.html

Makefile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
PYTHON=python3
44
VENVDIR=.venv
55
JOBS=8
6-
RENDER_COMMAND=$(VENVDIR)/bin/python3 build.py -j $(JOBS)
6+
OUTPUT_DIR=build
7+
RENDER_COMMAND=$(VENVDIR)/bin/python3 build.py -j $(JOBS) -o $(OUTPUT_DIR)
78

89
render: venv
910
$(RENDER_COMMAND)

build.py

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,12 @@ def create_parser():
3636
parser.add_argument("-j", "--jobs", type=int, default=1,
3737
help="How many parallel jobs to run (if supported). "
3838
"Integer, default 1.")
39+
parser.add_argument(
40+
"-o",
41+
"--output-dir",
42+
default="build", # synchronise with render.yaml -> deploy step
43+
help="Output directory, relative to root. Default 'build'.",
44+
)
3945

4046
return parser.parse_args()
4147

@@ -57,7 +63,7 @@ def create_index_file(html_root: Path, builder: str) -> None:
5763

5864
root_directory = Path(".").absolute()
5965
source_directory = root_directory
60-
build_directory = root_directory / "build" # synchronise with deploy-gh-pages.yaml -> deploy step
66+
build_directory = root_directory / args.output_dir
6167
doctree_directory = build_directory / ".doctrees"
6268

6369
# builder configuration

conf.py

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
# Add 'include_patterns' as a config variable
1212
from sphinx.config import Config
13-
Config.config_values['include_patterns'] = [], 'env', []
13+
Config.config_values["include_patterns"] = [], "env", []
1414
del Config
1515

1616
# -- Project information -----------------------------------------------------
@@ -21,7 +21,11 @@
2121
# -- General configuration ---------------------------------------------------
2222

2323
# Add any Sphinx extension module names here, as strings.
24-
extensions = ["pep_sphinx_extensions", "sphinx.ext.githubpages"]
24+
extensions = [
25+
"pep_sphinx_extensions",
26+
"sphinx.ext.intersphinx",
27+
"sphinx.ext.githubpages",
28+
]
2529

2630
# The file extensions of source files. Sphinx uses these suffixes as sources.
2731
source_suffix = {
@@ -46,6 +50,13 @@
4650
"pep-0012/pep-NNNN.rst",
4751
]
4852

53+
# Intersphinx configuration
54+
intersphinx_mapping = {
55+
'python': ('https://docs.python.org/3/', None),
56+
'packaging': ('https://packaging.python.org/en/latest/', None),
57+
}
58+
intersphinx_disabled_reftypes = []
59+
4960
# -- Options for HTML output -------------------------------------------------
5061

5162
# HTML output settings
@@ -60,4 +71,4 @@
6071
html_baseurl = "https://peps.python.org" # to create the CNAME file
6172
gettext_auto_build = False # speed-ups
6273

63-
templates_path = ['pep_sphinx_extensions/pep_theme/templates'] # Theme template relative paths from `confdir`
74+
templates_path = ["pep_sphinx_extensions/pep_theme/templates"] # Theme template relative paths from `confdir`

generate_rss.py

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@
77
from pathlib import Path
88
import re
99

10-
import docutils
11-
from docutils import frontend
10+
import docutils.frontend
1211
from docutils import nodes
1312
from docutils import utils
1413
from docutils.parsers import rst
@@ -25,14 +24,6 @@ def _format_rfc_2822(dt: datetime.datetime) -> str:
2524
return email.utils.format_datetime(dt, usegmt=True)
2625

2726

28-
# Monkeypatch nodes.Node.findall for forwards compatability
29-
if docutils.__version_info__ < (0, 18, 1):
30-
def findall(self, *args, **kwargs):
31-
return iter(self.traverse(*args, **kwargs))
32-
33-
nodes.Node.findall = findall
34-
35-
3627
entry.formatRFC2822 = feed.formatRFC2822 = _format_rfc_2822
3728
line_cache: dict[Path, dict[str, str]] = {}
3829

@@ -131,7 +122,7 @@ def pep_creation(full_path: Path) -> datetime.datetime:
131122

132123
def parse_rst(full_path: Path) -> nodes.document:
133124
text = full_path.read_text(encoding="utf-8")
134-
settings = frontend.OptionParser((rst.Parser,)).get_default_values()
125+
settings = docutils.frontend.get_default_settings(rst.Parser)
135126
document = utils.new_document(f'<{full_path}>', settings=settings)
136127
rst.Parser(rfc2822=True).parse(text, document)
137128
return document

pep-0012.rst

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -649,6 +649,66 @@ If you find that you need to use a backslash in your text, consider
649649
using inline literals or a literal block instead.
650650

651651

652+
Canonical Documentation and Intersphinx
653+
---------------------------------------
654+
655+
As :pep:`PEP 1 describes <1#pep-maintenance>`,
656+
PEPs are considered historical documents once marked Final,
657+
and their canonical documentation/specification should be moved elsewhere.
658+
To indicate this, use the ``canonical-docs`` directive
659+
or an appropriate subclass
660+
(currently ``canonical-pypa-spec`` for packaging standards).
661+
662+
Furthermore, you can use
663+
`Intersphinx references
664+
<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
665+
to other Sphinx sites,
666+
currently the `Python documentation <https://docs.python.org/>`_
667+
and `packaging.python.org <https://packaging.python.org/>`_,
668+
to easily cross-reference pages, sections and Python/C objects.
669+
This works with both the "canonical" directives and anywhere in your PEP.
670+
671+
Add the directive between the headers and the first section of the PEP
672+
(typically the Abstract)
673+
and pass as an argument an Intersphinx reference of the canonical doc/spec
674+
(or if the target is not on a Sphinx site, a `reST hyperlink <Hyperlinks_>`__).
675+
676+
For example,
677+
to create a banner pointing to the :mod:`python:sqlite3` docs,
678+
you would write the following::
679+
680+
.. canonical-doc:: :mod:`python:sqlite3`
681+
682+
which would generate the banner:
683+
684+
.. canonical-doc:: :mod:`python:sqlite3`
685+
686+
Or for a PyPA spec,
687+
such as the :ref:`packaging:core-metadata`,
688+
you would use::
689+
690+
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
691+
692+
which renders as:
693+
694+
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
695+
696+
The argument accepts arbitrary reST,
697+
so you can include multiple linked docs/specs and name them whatever you like,
698+
and you can also include directive content that will be inserted into the text.
699+
The following advanced example::
700+
701+
.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
702+
703+
Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
704+
705+
would render as:
706+
707+
.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:sqlite3.DataError` docs
708+
709+
Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
710+
711+
652712
Habits to Avoid
653713
===============
654714

0 commit comments

Comments
 (0)