Merge branch 'main' into patch-1

Author: chrysle

.pre-commit-config.yaml

@@ -2,4 +2,32 @@ 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

noxfile.py

@@ -4,8 +4,8 @@
 #   http://creativecommons.org/licenses/by-sa/3.0.
 
 import shutil
-import nox
 
+import nox
 
 nox.options.sessions = []
 
@@ -20,7 +20,7 @@ def translation(session):
     session.run(
         "sphinx-build",
         "-b", "gettext",  # build gettext-style message catalogs (.pot file)
-        "-d", ".nox/.doctrees/", # path to put the cache
+        "-d", session.cache_dir / ".doctrees", # path to put the cache
         "source/",  # where the rst files are located
         target_dir, # where to put the .pot file
     )
@@ -33,13 +33,9 @@ def build(session, autobuild=False):
     """
     session.install("-r", "requirements.txt")
 
-    target_build_dir = "build"
-
-    shutil.rmtree(target_build_dir, ignore_errors=True)
-
     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"
@@ -52,11 +48,12 @@ def build(session, autobuild=False):
         command, *extra_args,
         "-j", "auto",  # parallelize the build
         "-b", "html",  # use HTML builder
+        "-d", session.cache_dir / ".doctrees", # path to put the cache
         "-n",  # nitpicky warn about all missing references
         "-W",  # Treat warnings as errors.
         *session.posargs,
         "source",  # where the rst files are located
-        target_build_dir,  # where to put the html output
+        "build",  # where to put the html output
     )
 
 
@@ -78,6 +75,7 @@ def linkcheck(session):
     session.run(
         "sphinx-build",
         "-b", "linkcheck", # use linkcheck builder
+        "-d", session.cache_dir / ".doctrees", # path to put the cache
         "--color",
         "-n", "-W", "--keep-going",  # be strict
         "source", # where the rst files are located

requirements.txt

@@ -1,7 +1,6 @@
-sphinx==4.5.0
-sphinx-autobuild==0.7.1
-sphinx-inline-tabs==2021.4.11b9
-python-docs-theme==2023.9
-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/assets/py.png

@@ -88,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']
 
@@ -133,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 = []
@@ -150,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.
@@ -183,7 +181,7 @@
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #
-# html_favicon = None
+html_favicon = 'assets/py.png'
 
 # 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,
@@ -211,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.
@@ -379,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 = [

source/conf.py

@@ -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
 ---------
 
@@ -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

source/contribute.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

source/discussions/deploying-python-applications.rst

@@ -4,9 +4,6 @@
 install_requires vs requirements files
 ======================================
 
-.. contents:: Contents
-   :local:
-
 
 install_requires
 ----------------

source/discussions/install-requires-vs-requirements.rst

@@ -82,9 +82,12 @@ For example, here is a table for using :ref:`hatch`:
     requires = ["hatchling"]
     build-backend = "hatchling.build"
 
-With such a table in the :file:`pyproject.toml` file, a "frontend" tool like
-:ref:`build` can run your chosen build tool's "backend" to create the build
-artifacts. Your build tool may also provide its own frontend. An install tool
+With such a table in the :file:`pyproject.toml` file,
+a ":term:`frontend <Build Frontend>`" tool like
+:ref:`build` can run your chosen
+build tool's ":term:`backend <Build Backend>`"
+to create the build artifacts.
+Your build tool may also provide its own frontend. An install tool
 like :ref:`pip` also acts as a frontend when it runs your build tool's backend
 to install from a source distribution.
 

source/flow.rst

@@ -12,6 +12,36 @@ Glossary
         extensions.
 
 
+    Build Backend
+
+        A library that takes a source tree or
+        :term:`source distribution <Source Distribution (or "sdist")>`
+        and builds a source distribution or :term:`wheel <Wheel>` from it.
+        The build is delegated to the backend by a
+        :term:`frontend <Build Frontend>`.
+        All backends offer a standardized interface.
+
+        Examples of build backends are
+        :ref:`flit's flit-core <flit>`,
+        :ref:`hatch's hatchling <hatch>`,
+        :ref:`maturin`,
+        :ref:`meson-python`,
+        :ref:`scikit-build-core`,
+        and :ref:`setuptools`.
+
+
+    Build Frontend
+
+        A tool that users might run
+        that takes arbitrary source trees or
+        :term:`source distributions <Source Distribution (or "sdist")>`
+        and builds source distributions or :term:`wheels <Wheel>` from them.
+        The actual building is delegated to each source tree's
+        :term:`build backend <Build Backend>`.
+
+        Examples of build frontends are :ref:`pip` and :ref:`build`.
+
+
     Built Distribution
 
         A :term:`Distribution <Distribution Package>` format containing files
@@ -222,11 +252,10 @@ Glossary
     Version Specifier
 
        The version component of a :term:`Requirement Specifier`. For example,
-       the ">=1.3" portion of "foo>=1.3".  :pep:`440` contains
-       a :pep:`full specification
-       <440#version-specifiers>` of the
-       specifiers that Python packaging currently supports.  Support for PEP440
-       was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0.
+       the ">=1.3" portion of "foo>=1.3".  Read the :ref:`Version specifier specification
+       <version-specifiers>` for a full description of the
+       specifiers that Python packaging currently supports.  Support for this
+       specification was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0.
 
     Virtual Environment