From 1534bccbd061785c0bda5739a39e0f638abdd815 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Rom=C3=A1n?= <cesar@coatl.dev>
Date: Wed, 23 Apr 2025 17:31:40 -0700
Subject: [PATCH 1/5] docs: update readthedocs configuration and requirements

---
 .readthedocs.yaml |  6 +++++-
 requirements.txt  | 13 +++++++------
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index fe012dd98..90e9a9bbc 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -9,7 +9,11 @@ sphinx:
    # https://github.com/pyca/cryptography/issues/5863#issuecomment-792343136
    builder: dirhtml
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 python:
-   version: 3.8
    install:
    - requirements: requirements.txt
diff --git a/requirements.txt b/requirements.txt
index c4113b12b..5c710c86b 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,6 +1,7 @@
-sphinx==4.3.1
-sphinx-autobuild==0.7.1
-sphinx-inline-tabs==2021.4.11b9
-python-docs-theme==2021.5
-sphinx-copybutton==0.4.0
-git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme
+furo==2024.8.6
+sphinx==7.2.6
+sphinx-autobuild==2021.3.14
+sphinx-inline-tabs==2023.4.21
+sphinx-copybutton==0.5.2
+sphinx-toolbox==3.5.0
+sphinx-jsonschema==1.19.1

From e69daedb432ee38d71350d90d236ac10cbfef61c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Rom=C3=A1n?= <cesar@coatl.dev>
Date: Wed, 23 Apr 2025 17:34:46 -0700
Subject: [PATCH 2/5] chore: update sphinx configuration file

---
 source/conf.py | 573 +++++++++++++++----------------------------------
 1 file changed, 173 insertions(+), 400 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 600c451c4..61b947346 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -1,449 +1,222 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# The Python Packaging Guide documentation build configuration file, created by
-# sphinx-quickstart on Sun Dec 13 14:07:23 2009.
-#
-# This file is execfile()d with the current directory set to its containing
-# dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    'sphinx.ext.extlinks',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx_inline_tabs',
-    'sphinx_copybutton',
-]
+# -- Project information ---------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-# config for copy button
-copybutton_prompt_text = r">>> |\.\.\. |\$ |> "
-copybutton_prompt_is_regexp = True
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
-
-# The encoding of source files.
-#
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# -- Project information -----------------------------------------------------
-
-github_url = 'https://github.com'
-github_repo_org = 'pypa'
-github_repo_name = 'packaging.python.org'
-github_repo_slug = f'{github_repo_org}/{github_repo_name}'
-github_repo_url = f'{github_url}/{github_repo_slug}'
-github_repo_issues_url = f'{github_url}/{github_repo_slug}/issues'
-github_sponsors_url = f'{github_url}/sponsors'
-
-# General information about the project.
-project = u'Python Packaging User Guide'
-copyright = u'2013–2020, PyPA'
-author = 'Python Packaging Authority'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ''
-# The full version, including alpha/beta/rc tags.
-release = ''
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-locale_dirs = ['../locales']
-
-gettext_auto_build = True  # Build MO files from PO on each build
-
-# making all documents use single text domain
-gettext_compact = "messages"
+import os
 
-gettext_location = True  # Include location info in the translation files
+# Some options are only enabled for the main packaging.python.org deployment builds
+RTD_BUILD = bool(os.getenv("READTHEDOCS"))
+RTD_PR_BUILD = RTD_BUILD and os.getenv("READTHEDOCS_VERSION_TYPE") == "external"
+RTD_URL = os.getenv("READTHEDOCS_CANONICAL_URL")
+RTD_CANONICAL_BUILD = (
+    RTD_BUILD and not RTD_PR_BUILD and "packaging.python.org" in RTD_URL
+)
 
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#
-# today = ''
-#
-# Else, today_fmt is used as the format for a strftime call.
-#
-# today_fmt = '%B %d, %Y'
+project = "Python Packaging User Guide"
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+copyright = "2013–2020, PyPA"
+author = "Python Packaging Authority"
 
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-# Ref: python-attrs/attrs#571
-default_role = 'any'  # makes single backticks autofind targets
+# -- General configuration -------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#
-# add_function_parentheses = True
+root_doc = "index"
 
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#
-# add_module_names = False
+extensions = [
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx_inline_tabs",
+    "sphinx_copybutton",
+    "sphinx_toolbox.collapse",
+    "sphinx-jsonschema",
+]
 
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#
-# show_authors = False
+nitpicky = True
+nitpick_ignore = [
+    ("envvar", "PATH"),
+    ("py:func", "find_packages"),
+    ("py:func", "setup"),
+    ("py:func", "importlib.metadata.entry_points"),
+    ("py:class", "importlib.metadata.EntryPoint"),
+    ("py:func", "setuptools.find_namespace_packages"),
+    ("py:func", "setuptools.find_packages"),
+    ("py:func", "setuptools.setup"),
+]
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+default_role = "any"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
+# -- Options for internationalization --------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization
 
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
+language = "en"
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-# todo_include_todos = False
+locale_dirs = ["../locales"]
 
+gettext_auto_build = True
+gettext_compact = "messages"
+gettext_location = True
 
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'pypa_theme'
+html_title = "Python Packaging User Guide"
+html_theme = "furo"
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
 html_theme_options = {
-    'collapsiblesidebar': True,
-    'externalrefs': True,
-    'navigation_depth': 2,
-    'issues_url': github_repo_issues_url,
+    "source_edit_link": "https://github.com/pypa/packaging.python.org/edit/main/source/{filename}",
+    "source_view_link": "https://github.com/pypa/packaging.python.org/blob/main/source/{filename}?plain=true",
 }
 
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = ['themes']
-
-# The name for this set of Sphinx documents.
-# "<project> v<release> documentation" by default.
-#
-html_title = 'Python Packaging User Guide'
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#
-# html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#
-# html_logo = None
-
-# The name of an image file (relative to this directory) to use as a favicon of
-# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#
-# html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-html_css_files = ['overrides.css']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#
-# html_extra_path = []
-
-# If not None, a 'Last updated on:' timestamp is inserted at every page
-# bottom, using the given strftime format.
-# The empty string is equivalent to '%b %d, %Y'.
-#
-html_last_updated_fmt = ''
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#
-
-# Custom sidebar templates, filenames relative to this file.
-html_sidebars = {
-    '**': ['globaltoc.html', 'relations.html'],
-    'index': ['globaltoc.html']
-}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-#
-# html_domain_indices = True
-
-# If false, no index is generated.
-#
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#
-# html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#
-# html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#
-# html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
-#
-# html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# 'ja' uses this config value.
-# 'zh' user can custom change `jieba` dictionary path.
-#
-# html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#
-# html_search_scorer = 'scorer.js'
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'pythonpackagingguide-authdoc'
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-     # The paper size ('letterpaper' or 'a4paper').
-     #
-     # 'papersize': 'letterpaper',
-
-     # The font size ('10pt', '11pt' or '12pt').
-     #
-     # 'pointsize': '10pt',
-
-     # Additional stuff for the LaTeX preamble.
-     #
-     # 'preamble': '',
-
-     # Latex figure (float) alignment
-     #
-     # 'figure_align': 'htbp',
-}
+html_favicon = "assets/py.png"
+html_last_updated_fmt = ""
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'pythonpackagingguide.tex', 'Python Packaging User Guide',
-     'Python Packaging Authority', 'manual'),
+_metrics_js_files = [
+    (
+        "https://analytics.python.org/js/script.outbound-links.js",
+        {"data-domain": "packaging.python.org", "defer": "defer"},
+    ),
+]
+html_js_files = []
+if RTD_CANONICAL_BUILD:
+    # Enable collection of the visitor metrics reported at
+    # https://plausible.io/packaging.python.org
+    html_js_files.extend(_metrics_js_files)
+
+html_extra_path = [
+    "../extra",
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-#
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#
-# latex_appendices = []
+# -- Options for HTML help output ------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 
-# It false, will not define \strong, \code,     itleref, \crossref ... but only
-# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
-# packages.
-#
-# latex_keep_old_macro_names = True
+htmlhelp_basename = "pythonpackagingguide-authdoc"
 
-# If false, no module index is generated.
-#
-# latex_domain_indices = True
+# -- Options for LaTeX output ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
 
+latex_elements = {}
+latex_documents = [
+    (
+        root_doc,
+        "pythonpackagingguide.tex",
+        "Python Packaging User Guide",
+        "Python Packaging Authority",
+        "manual",
+    ),
+]
 
-# -- Options for manual page output ---------------------------------------
+# -- Options for manual page output ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output
 
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'pythonpackagingguide', 'Python Packaging User Guide',
-     [author], 1)
+    (root_doc, "pythonpackagingguide", "Python Packaging User Guide", [author], 1)
 ]
 
-# If true, show URL addresses after external links.
-#
-# man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
+# -- Options for Texinfo output --------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-texinfo-output
 
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pythonpackagingguide', 'Python Packaging User Guide',
-     author, 'pythonpackagingguide', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        root_doc,
+        "pythonpackagingguide",
+        "Python Packaging User Guide",
+        author,
+        "pythonpackagingguide",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
-# Documents to append as an appendix to all manuals.
-#
-# texinfo_appendices = []
+# -- Options for the linkcheck builder -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
 
-# If false, no module index is generated.
-#
-# texinfo_domain_indices = True
+linkcheck_ignore = [
+    "http://localhost:\\d+",
+    "https://packaging.python.org/en/latest/specifications/schemas/.*",
+    "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
+    "https://pypi.org/manage/*",
+    "https://test.pypi.org/manage/*",
+    # Temporarily ignored. Ref:
+    # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
+    "https://www.breezy-vcs.org/*",
+    # Ignore while StackOverflow is blocking GitHub CI. Ref:
+    # https://github.com/pypa/packaging.python.org/pull/1474
+    "https://stackoverflow.com/*",
+    "https://pyscaffold.org/*",
+    "https://anaconda.org",
+]
+linkcheck_retries = 5
+# Ignore anchors for common targets when we know they likely won't be found
+linkcheck_anchors_ignore_for_url = [
+    # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
+    r"https://github\.com/",
+    # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
+    # https://github.com/pypa/packaging.python.org/issues/1744
+    r"https://pypi\.org/",
+]
 
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#
-# texinfo_show_urls = 'footnote'
+# -- Options for extlinks ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration
 
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#
-# texinfo_no_detailmenu = False
+github_url = "https://github.com"
+github_repo_org = "pypa"
+github_repo_name = "packaging.python.org"
+github_repo_slug = f"{github_repo_org}/{github_repo_name}"
+github_repo_url = f"{github_url}/{github_repo_slug}"
+github_repo_issues_url = f"{github_url}/{github_repo_slug}/issues"
+github_sponsors_url = f"{github_url}/sponsors"
 
-# -- Options for extlinks extension ---------------------------------------
 extlinks = {
-    'issue': (f'{github_repo_issues_url}/%s', '#'),  # noqa: WPS323
-    'pr': (f'{github_repo_url}/pull/%s', 'PR #'),  # noqa: WPS323
-    'commit': (f'{github_repo_url}/commit/%s', ''),  # noqa: WPS323
-    'gh': (f'{github_url}/%s', 'GitHub: '),  # noqa: WPS323
-    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
+    "issue": (f"{github_repo_issues_url}/%s", "#%s"),
+    "pr": (f"{github_repo_url}/pull/%s", "PR #%s"),
+    "commit": (f"{github_repo_url}/commit/%s", "%s"),
+    "gh": (f"{github_url}/%s", "GitHub: %s"),
+    "user": (f"{github_sponsors_url}/%s", "@%s"),
 }
 
-linkcheck_ignore = [
-    "http://localhost:\d+",
-    # This is an example that showing to the reader
-    "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
-    # Ignoring it as it will redirect to login page if reader hasn't logged in.
-    "https://pypi.org/manage/*",
-    "https://test.pypi.org/manage/*",
-]
+# -- Options for intersphinx ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 
-# Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'boltons': ('https://boltons.readthedocs.io/en/latest/', None),
-    'build': ('https://pypa-build.readthedocs.io/en/stable/', None),
-    'cffi': ('https://cffi.readthedocs.io/en/latest/', None),
-    'conda': ('https://conda.io/en/latest/', None),
-    'devpi': ('https://devpi.net/docs/devpi/devpi/latest/+doc', None),
-    'dh-virtualenv': ('https://dh-virtualenv.readthedocs.io/en/latest/', None),
-    'distlib': ('https://distlib.readthedocs.io/en/latest/', None),
-    'flexx': ('https://flexx.readthedocs.io/en/latest/', None),
-    'nox': ('https://nox.thea.codes/en/latest/', None),
-    'openstack': ('https://docs.openstack.org/glance/latest/', None),
-    'packaging': ('https://packaging.pypa.io/en/latest/', None),
-    'packaging.python.org': ('https://packaging.python.org/', None),
-    'pip': ('https://pip.pypa.io/en/latest/', None),
-    'pipenv': ('https://pipenv.pypa.io/en/latest/', None),
-    'piwheels': ('https://piwheels.readthedocs.io/en/latest/', None),
-    'pybind11': ('https://pybind11.readthedocs.io/en/stable/', None),
-    'pynsist': ('https://pynsist.readthedocs.io/en/latest/', None),
-    'pypa': ('https://www.pypa.io/en/latest/', None),
-    'python': ('https://docs.python.org/3', None),
-    'python-guide': ('https://docs.python-guide.org', None),
-    'python2': ('https://docs.python.org/2', None),
-    'setuptools': ('https://setuptools.readthedocs.io/en/latest/', None),
-    'spack': ('https://spack.readthedocs.io/en/latest/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
-    'tox': ('https://tox.readthedocs.io/en/latest/', None),
-    'twine': ('https://twine.readthedocs.io/en/stable/', None),
-    'virtualenv': ('https://virtualenv.pypa.io/en/stable/', None),
+    "boltons": ("https://boltons.readthedocs.io/en/latest/", None),
+    "bottle": ("https://bottlepy.org/docs/dev/", None),
+    "build": ("https://pypa-build.readthedocs.io/en/stable/", None),
+    "cffi": ("https://cffi.readthedocs.io/en/latest/", None),
+    "conda": ("https://conda.io/en/latest/", None),
+    "devpi": ("https://devpi.net/docs/devpi/devpi/latest/+doc", None),
+    "dh-virtualenv": ("https://dh-virtualenv.readthedocs.io/en/latest/", None),
+    "distlib": ("https://distlib.readthedocs.io/en/latest/", None),
+    "flexx": ("https://flexx.readthedocs.io/en/latest/", None),
+    "flit": ("https://flit.pypa.io/en/stable/", None),
+    "nox": ("https://nox.thea.codes/en/latest/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "openstack": ("https://docs.openstack.org/glance/latest/", None),
+    "packaging": ("https://packaging.pypa.io/en/latest/", None),
+    "pip": ("https://pip.pypa.io/en/latest/", None),
+    "pipenv": ("https://pipenv.pypa.io/en/latest/", None),
+    "piwheels": ("https://piwheels.readthedocs.io/en/latest/", None),
+    "pybind11": ("https://pybind11.readthedocs.io/en/stable/", None),
+    "pynsist": ("https://pynsist.readthedocs.io/en/latest/", None),
+    "pypa": ("https://www.pypa.io/en/latest/", None),
+    "python": ("https://docs.python.org/3", None),
+    "python-guide": ("https://docs.python-guide.org", None),
+    "setuptools": ("https://setuptools.pypa.io/en/latest/", None),
+    "spack": ("https://spack.readthedocs.io/en/latest/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "tox": ("https://tox.wiki/en/latest/", None),
+    "twine": ("https://twine.readthedocs.io/en/stable/", None),
+    "virtualenv": ("https://virtualenv.pypa.io/en/stable/", None),
+    "warehouse": ("https://warehouse.pypa.io/", None),
 }
 
-
-# If this is True, todo and todolist produce output, else they produce nothing.
-# The default is False.
+# -- Options for todo extension --------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
 
 todo_include_todos = True
 
-nitpicky = True
+# -- Options for sphinx-copybutton -----------------------------------------------------
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html
 
-# NOTE: consider having a separate ignore file
-# Ref: https://stackoverflow.com/a/30624034/595220
-nitpick_ignore = [
-    ('envvar', 'PATH'),
-    ('py:func', 'find_packages'),
-    ('py:func', 'setup'),
-    ('py:func', 'importlib.metadata.entry_points'),  # remove when 3.10 is released
-    ('py:class', 'importlib.metadata.EntryPoint'),  # remove when 3.10 is released
-    ('py:func', 'setuptools.find_namespace_packages'),
-    ('py:func', 'setuptools.find_packages'),
-    ('py:func', 'setuptools.setup'),
-]
+copybutton_prompt_text = r">>> |\.\.\. |\$ |> "
+copybutton_prompt_is_regexp = True
\ No newline at end of file

From 8b47c3b9b7bf7dc467ac2166f41c0b3bb3cabc99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Rom=C3=A1n?= <cesar@coatl.dev>
Date: Wed, 23 Apr 2025 17:42:01 -0700
Subject: [PATCH 3/5] chore: update links to repo

---
 source/conf.py          | 10 +++++-----
 source/contribute.rst   |  8 ++++----
 source/key_projects.rst |  2 +-
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/source/conf.py b/source/conf.py
index 61b947346..1284f8737 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -64,8 +64,8 @@
 html_theme = "furo"
 
 html_theme_options = {
-    "source_edit_link": "https://github.com/pypa/packaging.python.org/edit/main/source/{filename}",
-    "source_view_link": "https://github.com/pypa/packaging.python.org/blob/main/source/{filename}?plain=true",
+    "source_edit_link": "https://github.com/coatl-dev/packaging.python.org/edit/main/source/{filename}",
+    "source_view_link": "https://github.com/coatl-dev/packaging.python.org/blob/main/source/{filename}?plain=true",
 }
 
 html_favicon = "assets/py.png"
@@ -138,10 +138,10 @@
     "https://pypi.org/manage/*",
     "https://test.pypi.org/manage/*",
     # Temporarily ignored. Ref:
-    # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
+    # https://github.com/coatl-dev/packaging.python.org/pull/1308#issuecomment-1775347690
     "https://www.breezy-vcs.org/*",
     # Ignore while StackOverflow is blocking GitHub CI. Ref:
-    # https://github.com/pypa/packaging.python.org/pull/1474
+    # https://github.com/coatl-dev/packaging.python.org/pull/1474
     "https://stackoverflow.com/*",
     "https://pyscaffold.org/*",
     "https://anaconda.org",
@@ -152,7 +152,7 @@
     # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
     r"https://github\.com/",
     # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
-    # https://github.com/pypa/packaging.python.org/issues/1744
+    # https://github.com/coatl-dev/packaging.python.org/issues/1744
     r"https://pypi\.org/",
 ]
 
diff --git a/source/contribute.rst b/source/contribute.rst
index c5edb0792..d40586c5c 100644
--- a/source/contribute.rst
+++ b/source/contribute.rst
@@ -18,9 +18,9 @@ Most of the work on the |PyPUG| takes place on the
 `open issues`__ and `pull requests`__. If you're planning to write or edit
 the guide, please read the :ref:`style guide <contributing_style_guide>`.
 
-.. __: https://github.com/pypa/packaging.python.org/
-.. __: https://github.com/pypa/packaging.python.org/issues
-.. __: https://github.com/pypa/packaging.python.org/pulls
+.. __: https://github.com/coatl-dev/packaging.python.org/
+.. __: https://github.com/coatl-dev/packaging.python.org/issues
+.. __: https://github.com/coatl-dev/packaging.python.org/pulls
 
 By contributing to the |PyPUG|, you're expected to follow the PSF's
 `Code of Conduct`__.
@@ -83,7 +83,7 @@ please open an issue on `Github`_.
 
 .. _Weblate: https://weblate.org/
 .. _packaging.python.org: https://hosted.weblate.org/projects/pypa/packaging-python-org/
-.. _Github: https://github.com/pypa/packaging.python.org/issues
+.. _Github: https://github.com/coatl-dev/packaging.python.org/issues
 .. _reStructuredText syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
 Adding a language
diff --git a/source/key_projects.rst b/source/key_projects.rst
index 39ebfab03..4421f3e75 100644
--- a/source/key_projects.rst
+++ b/source/key_projects.rst
@@ -202,7 +202,7 @@ Python Packaging User Guide
 ===========================
 
 :doc:`Docs <packaging.python.org:index>` |
-`Issues <https://github.com/pypa/packaging.python.org/issues>`__ |
+`Issues <https://github.com/coatl-dev/packaging.python.org/issues>`__ |
 `GitHub <https://github.com/pypa/packaging.python.org>`__
 
 This guide!

From 7df6b48ef35bf9ea11243364a9d0b3b70ec9e9f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Rom=C3=A1n?= <cesar@coatl.dev>
Date: Wed, 23 Apr 2025 18:04:25 -0700
Subject: [PATCH 4/5] chore: fix ToC error

---
 source/discussions/deploying-python-applications.rst     | 4 ----
 source/discussions/install-requires-vs-requirements.rst  | 4 ----
 source/guides/analyzing-pypi-package-downloads.rst       | 4 ----
 source/guides/distributing-packages-using-setuptools.rst | 4 ----
 source/guides/index-mirrors-and-caches.rst               | 4 ----
 source/guides/installing-scientific-packages.rst         | 4 ----
 source/guides/packaging-binary-extensions.rst            | 3 ---
 source/guides/supporting-multiple-python-versions.rst    | 4 ----
 source/guides/supporting-windows-using-appveyor.rst      | 4 ----
 source/overview.rst                                      | 3 ---
 source/specifications/core-metadata.rst                  | 3 ---
 source/specifications/direct-url.rst                     | 3 ---
 source/tutorials/installing-packages.rst                 | 5 -----
 13 files changed, 49 deletions(-)

diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst
index de781d9fd..84d6760de 100644
--- a/source/discussions/deploying-python-applications.rst
+++ b/source/discussions/deploying-python-applications.rst
@@ -6,10 +6,6 @@ Deploying Python applications
 :Page Status: Incomplete
 :Last Reviewed: 2021-8-24
 
-.. contents:: Contents
-   :local:
-
-
 Overview
 ========
 
diff --git a/source/discussions/install-requires-vs-requirements.rst b/source/discussions/install-requires-vs-requirements.rst
index 95578bca8..3d2e3a806 100644
--- a/source/discussions/install-requires-vs-requirements.rst
+++ b/source/discussions/install-requires-vs-requirements.rst
@@ -4,10 +4,6 @@
 install_requires vs requirements files
 ======================================
 
-.. contents:: Contents
-   :local:
-
-
 install_requires
 ----------------
 
diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
index f66cd5132..57168ead1 100644
--- a/source/guides/analyzing-pypi-package-downloads.rst
+++ b/source/guides/analyzing-pypi-package-downloads.rst
@@ -7,10 +7,6 @@ to learn more about downloads of a package (or packages) hosted on PyPI. For
 example, you can use it to discover the distribution of Python versions used to
 download a package.
 
-.. contents:: Contents
-   :local:
-
-
 Background
 ==========
 
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
index c457a1e3b..4c9dcc4d7 100644
--- a/source/guides/distributing-packages-using-setuptools.rst
+++ b/source/guides/distributing-packages-using-setuptools.rst
@@ -19,10 +19,6 @@ Packages <userguide/index>` in the :ref:`setuptools` docs, but note
 that some advisory content there may be outdated. In the event of
 conflicts, prefer the advice in the Python Packaging User Guide.
 
-.. contents:: Contents
-   :local:
-
-
 Requirements for packaging and distributing
 ===========================================
 1. First, make sure you have already fulfilled the :ref:`requirements for
diff --git a/source/guides/index-mirrors-and-caches.rst b/source/guides/index-mirrors-and-caches.rst
index 18dc3463e..39f2fd35b 100644
--- a/source/guides/index-mirrors-and-caches.rst
+++ b/source/guides/index-mirrors-and-caches.rst
@@ -7,10 +7,6 @@ Package index mirrors and caches
 :Page Status: Incomplete
 :Last Reviewed: 2014-12-24
 
-.. contents:: Contents
-   :local:
-
-
 Mirroring or caching of PyPI can be used to speed up local package installation,
 allow offline work, handle corporate firewalls or just plain Internet flakiness.
 
diff --git a/source/guides/installing-scientific-packages.rst b/source/guides/installing-scientific-packages.rst
index a5feb4ad5..4f96089ad 100644
--- a/source/guides/installing-scientific-packages.rst
+++ b/source/guides/installing-scientific-packages.rst
@@ -4,10 +4,6 @@
 Installing scientific packages
 ==============================
 
-.. contents:: Contents
-   :local:
-
-
 Scientific software tends to have more complex dependencies than most, and
 it will often have multiple build options to take advantage of different
 kinds of hardware, or to interoperate with different pieces of external
diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
index 6f9088333..0faac4f88 100644
--- a/source/guides/packaging-binary-extensions.rst
+++ b/source/guides/packaging-binary-extensions.rst
@@ -13,9 +13,6 @@ C API for use by other software. One of the most common uses of this C API
 is to create importable C extensions that allow things which aren't
 always easy to achieve in pure Python code.
 
-.. contents:: Contents
-   :local:
-
 An overview of binary extensions
 ================================
 
diff --git a/source/guides/supporting-multiple-python-versions.rst b/source/guides/supporting-multiple-python-versions.rst
index 42d8efab1..2c3a7edc0 100644
--- a/source/guides/supporting-multiple-python-versions.rst
+++ b/source/guides/supporting-multiple-python-versions.rst
@@ -7,10 +7,6 @@ Supporting multiple Python versions
 :Page Status: Incomplete
 :Last Reviewed: 2014-12-24
 
-.. contents:: Contents
-   :local:
-
-
 ::
 
   FIXME
diff --git a/source/guides/supporting-windows-using-appveyor.rst b/source/guides/supporting-windows-using-appveyor.rst
index 3a2d944a7..6014f6deb 100644
--- a/source/guides/supporting-windows-using-appveyor.rst
+++ b/source/guides/supporting-windows-using-appveyor.rst
@@ -10,10 +10,6 @@ service to provide Windows support for your project. This includes testing
 the code on Windows, and building Windows-targeted binaries for projects
 that use C extensions.
 
-.. contents:: Contents
-   :local:
-
-
 Background
 ==========
 
diff --git a/source/overview.rst b/source/overview.rst
index 5b233bbef..133111ff2 100644
--- a/source/overview.rst
+++ b/source/overview.rst
@@ -19,9 +19,6 @@ This overview provides a general-purpose decision tree for reasoning
 about Python's plethora of packaging options. Read on to choose the best
 technology for your next project.
 
-.. contents:: Contents
-   :local:
-
 Thinking about deployment
 -------------------------
 
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
index ef28081cc..0b16520eb 100644
--- a/source/specifications/core-metadata.rst
+++ b/source/specifications/core-metadata.rst
@@ -37,9 +37,6 @@ to a new format.
    more relaxed formatting rules even for metadata files that are nominally
    less than version 2.1.
 
-.. contents:: Contents
-   :local:
-
 Metadata-Version
 ================
 
diff --git a/source/specifications/direct-url.rst b/source/specifications/direct-url.rst
index 9b8180c47..605cfcce6 100644
--- a/source/specifications/direct-url.rst
+++ b/source/specifications/direct-url.rst
@@ -10,9 +10,6 @@ This document specifies a :file:`direct_url.json` file in the
 Direct URL Origin of the distribution. The layout of this file was originally
 specified in :pep:`610` and is formally documented here.
 
-.. contents:: Contents
-   :local:
-
 Specification
 =============
 
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
index c68ea6c18..8a82dd2ef 100644
--- a/source/tutorials/installing-packages.rst
+++ b/source/tutorials/installing-packages.rst
@@ -17,11 +17,6 @@ the term "distribution" is often not preferred, because it can easily be
 confused with a Linux distribution, or another larger software distribution
 like Python itself.
 
-
-.. contents:: Contents
-   :local:
-
-
 .. _installing_requirements:
 
 Requirements for Installing Packages

From ae92e1048c55e2d30c54f2a1bcd30ce570f97cbf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Rom=C3=A1n?= <cesar@coatl.dev>
Date: Wed, 23 Apr 2025 19:31:09 -0700
Subject: [PATCH 5/5] chore: fix ToC error 2

---
 source/guides/installing-using-linux-tools.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
index c91ce7924..55c30bb4b 100644
--- a/source/guides/installing-using-linux-tools.rst
+++ b/source/guides/installing-using-linux-tools.rst
@@ -7,9 +7,6 @@ Installing pip/setuptools/wheel with Linux Package Managers
 :Page Status: Incomplete
 :Last Reviewed: 2021-07-26
 
-.. contents:: Contents
-  :local:
-
 This section covers how to install :ref:`pip`, :ref:`setuptools`, and
 :ref:`wheel` using Linux package managers.