Merge branch 'main' into more-indices

.github/workflows/test.yml

@@ -1,7 +1,10 @@
 name: Test
 
-on: 
+on:
+  merge_group:
   push:
+    branches-ignore:
+    - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
   pull_request:
   schedule:
     - cron: "0 6 * * *" # daily at 6am
@@ -13,6 +16,7 @@ concurrency:
 jobs:
   build:
     name: ${{ matrix.noxenv }}
+    if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -26,7 +30,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.11"
           cache: 'pip'
           cache-dependency-path: 'requirements.txt'
 
@@ -37,3 +41,21 @@ jobs:
       - name: Nox ${{ matrix.noxenv }}
         run: |
           python -m nox -s ${{ matrix.noxenv }}
+
+
+  check:
+    # This job does nothing and is only used for the branch protection
+    # or multi-stage CI jobs, like making sure that all tests pass before
+    # a publishing job is started.
+    if: always()
+
+    needs:
+    - build
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-yaml
+  - id: end-of-file-fixer
+  - id: mixed-line-ending
+  - id: trailing-whitespace
+
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.2.6
+  hooks:
+  - id: codespell
+    args: ["-L", "ned"]
+
+- repo: local
+  hooks:
+  - id: disallow-caps
+    name: Disallow improper capitalization
+    language: pygrep
+    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
+    exclude: .pre-commit-config.yaml
+
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: v1.10.0
+  hooks:
+  - id: rst-backticks
+  - id: rst-directive-colons
+  - id: rst-inline-touching-normal

.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

noxfile.py

@@ -18,13 +18,14 @@ def translation(session):
     session.install("-r", "requirements.txt")
     target_dir = "locales"
     session.run(
-        "sphinx-build", 
+        "sphinx-build",
         "-b", "gettext",  # build gettext-style message catalogs (.pot file)
         "-d", ".nox/.doctrees/", # path to put the cache
         "source/",  # where the rst files are located
         target_dir, # where to put the .pot file
     )
 
+
 @nox.session()
 def build(session, autobuild=False):
     """
@@ -38,7 +39,7 @@ def build(session, autobuild=False):
 
     if autobuild:
         command = "sphinx-autobuild"
-        extra_args = "-H", "0.0.0.0"
+        extra_args = "--host", "0.0.0.0"
     else:
         # NOTE: This branch adds options that are unsupported by autobuild
         command = "sphinx-build"
@@ -75,10 +76,24 @@ def linkcheck(session):
     """
     session.install("-r", "requirements.txt")
     session.run(
-        "sphinx-build", 
+        "sphinx-build",
         "-b", "linkcheck", # use linkcheck builder
         "--color",
         "-n", "-W", "--keep-going",  # be strict
         "source", # where the rst files are located
         "build", # where to put the check output
     )
+
+
+@nox.session()
+def checkqa(session):
+    """
+    Format the guide using pre-commit.
+    """
+    session.install("pre-commit")
+    session.run(
+        "pre-commit",
+        "run",
+        "--all-files",
+        "--show-diff-on-failure",
+    )

requirements.txt

@@ -1,6 +1,6 @@
-sphinx==4.5.0
-sphinx-autobuild==0.7.1
-sphinx-inline-tabs==2021.4.11b9
-python-docs-theme==2022.1
-sphinx-copybutton==0.5.0
-pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
+furo==2023.9.10
+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

source/conf.py

@@ -36,6 +36,7 @@
     'sphinx.ext.todo',
     'sphinx_inline_tabs',
     'sphinx_copybutton',
+    'sphinx_toolbox.collapse',
 ]
 
 # config for copy button
@@ -87,7 +88,7 @@
 #
 # 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
+language = 'en'
 
 locale_dirs = ['../locales']
 
@@ -132,7 +133,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+#pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -149,16 +150,14 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pypa_theme'
+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,
+    "sidebar_hide_name": True,
+    # 'issues_url': github_repo_issues_url,  # FIXME: support this in furo?
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -176,7 +175,7 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-# html_logo = None
+html_logo = 'assets/py.png'
 
 # 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
@@ -210,10 +209,10 @@
 #
 
 # Custom sidebar templates, filenames relative to this file.
-html_sidebars = {
-    '**': ['globaltoc.html', 'relations.html'],
-    'index': ['globaltoc.html']
-}
+# html_sidebars = {
+#     '**': ['globaltoc.html', 'relations.html'],
+#     'index': ['globaltoc.html']
+# }
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -378,11 +377,11 @@
 
 # -- 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'),  # noqa: WPS323
+    'pr': (f'{github_repo_url}/pull/%s', 'PR #%s'),  # noqa: WPS323
+    'commit': (f'{github_repo_url}/commit/%s', '%s'),  # noqa: WPS323
+    'gh': (f'{github_url}/%s', 'GitHub: %s'),  # noqa: WPS323
+    'user': (f'{github_sponsors_url}/%s', '@%s'),  # noqa: WPS323
 }
 
 linkcheck_ignore = [
@@ -397,6 +396,7 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     '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),
@@ -407,7 +407,7 @@
     '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),
+    'packaging.python.org': ('https://packaging.python.org/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),
@@ -416,10 +416,10 @@
     '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.readthedocs.io/en/latest/', 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.readthedocs.io/en/latest/', None),
+    'tox': ('https://tox.wiki/en/latest/', None),
     'twine': ('https://twine.readthedocs.io/en/stable/', None),
     'virtualenv': ('https://virtualenv.pypa.io/en/stable/', None),
 }

source/contribute.rst

@@ -32,9 +32,12 @@ Documentation types
 ===================
 
 This project consists of four distinct documentation types with specific
-purposes. When proposing new additions to the project please pick the
+purposes. The project aspires to follow the `Diátaxis process`_
+for creating quality documentation. When proposing new additions to the project please pick the
 appropriate documentation type.
 
+.. _Diátaxis process: https://diataxis.fr/
+
 Tutorials
 ---------
 
@@ -63,7 +66,7 @@ document <discussions/install-requires-vs-requirements>`.
 Specifications
 --------------
 
-Specifications are reference documention focused on comprehensively documenting
+Specifications are reference documentation focused on comprehensively documenting
 an agreed-upon interface for interoperability between packaging tools.
 :doc:`example specification-style document <specifications/core-metadata>`.
 
@@ -75,15 +78,15 @@ We use `Weblate`_ to manage translations of this project.
 Please visit the `packaging.python.org`_ project on Weblate to contribute.
 
 If you are experiencing issues while you are working on translations,
-please open an issue on `Github`_.
+please open an issue on `GitHub`_.
 
 .. tip::
 
    Any translations of this project should follow `reStructuredText syntax`_.
 
 .. _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/pypa/packaging.python.org/issues
 .. _reStructuredText syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
 Adding a language
@@ -131,9 +134,9 @@ need:
 
       python -m pip install --user nox
 
-2. Python 3.8. Our build scripts are usually tested with Python 3.8 only.
+2. Python 3.11. Our build scripts are usually tested with Python 3.11 only.
    See the :doc:`Hitchhiker's Guide to Python installation instructions <python-guide:starting/installation>`
-   to install Python 3.8 on your operating system.
+   to install Python 3.11 on your operating system.
 
 To build the guide, run the following shell command in the project's root folder:
 

source/discussions/deploying-python-applications.rst

@@ -6,9 +6,6 @@ Deploying Python applications
 :Page Status: Incomplete
 :Last Reviewed: 2021-8-24
 
-.. contents:: Contents
-   :local:
-
 
 Overview
 ========
@@ -73,7 +70,7 @@ directory, independent of any other Python installation on the computer.
 
 A big advantage of Pynsist is that the Windows packages can be built on Linux.
 There are several examples for different kinds of programs (console, GUI) in
-the `documentation <pynsist:index>`. The tool is released
+the :any:`documentation <pynsist:index>`. The tool is released
 under the MIT-licence.
 
 Application bundles
@@ -92,12 +89,12 @@ py2exe
 ^^^^^^
 
 `py2exe <https://pypi.org/project/py2exe/>`__ is a distutils extension which
-allows to build standalone Windows executable programs (32-bit and 64-bit) 
-from Python scripts. Python versions included in the official development 
+allows to build standalone Windows executable programs (32-bit and 64-bit)
+from Python scripts. Python versions included in the official development
 cycle are supported (refers to `Status of Python branches`__). py2exe can
 build console executables and windows (GUI) executables. Building windows
 services, and DLL/EXE COM servers might work but it is not actively supported.
-The distutils extension is released under the MIT-licence and Mozilla 
+The distutils extension is released under the MIT-licence and Mozilla
 Public License 2.0.
 
 .. __: https://devguide.python.org/#status-of-python-branches
@@ -108,8 +105,8 @@ macOS
 py2app
 ^^^^^^
 
-`py2app <https://pypi.org/project/py2app/>`__ is a Python setuptools 
-command which will allow you to make standalone macOS application 
+`py2app <https://pypi.org/project/py2app/>`__ is a Python setuptools
+command which will allow you to make standalone macOS application
 bundles and plugins from Python scripts. Note that py2app MUST be used
 on macOS to build applications, it cannot create Mac applications on other
 platforms. py2app is released under the MIT-license.
@@ -120,11 +117,11 @@ Unix (including Linux and macOS)
 pex
 ^^^
 
-`pex <https://pypi.org/project/pex/>`__ is  a library for generating .pex 
-(Python EXecutable) files which are executable Python environments in the 
-spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441` 
-and makes the deployment of Python applications as simple as cp. pex files may 
-even include multiple platform-specific Python distributions, meaning that a 
+`pex <https://pypi.org/project/pex/>`__ is  a library for generating .pex
+(Python EXecutable) files which are executable Python environments in the
+spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441`
+and makes the deployment of Python applications as simple as cp. pex files may
+even include multiple platform-specific Python distributions, meaning that a
 single pex file can be portable across Linux and macOS. pex is released under the
 Apache License 2.0.