Merge branch 'main' into Requires-Python

wimglenn · web-flow · commit db58433c3265 · 2023-11-05T21:07:36.000-06:00
diff --git a/requirements.txt b/requirements.txt
@@ -1,7 +1,7 @@
-sphinx==4.5.0
+sphinx==7.2.6
 sphinx-autobuild==2021.3.14
-sphinx-inline-tabs==2021.4.11b9
+sphinx-inline-tabs==2023.4.21
 python-docs-theme==2023.9
-sphinx-copybutton==0.5.0
+sphinx-copybutton==0.5.2
 pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
 sphinx-toolbox==3.5.0
diff --git a/source/conf.py b/source/conf.py
@@ -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']
 
@@ -379,11 +379,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 = [
diff --git a/source/contribute.rst b/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
 ---------
 
diff --git a/source/flow.rst b/source/flow.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.
 
diff --git a/source/glossary.rst b/source/glossary.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
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -15,7 +15,7 @@ development as a whole.  For example, it does not provide guidance or tool
 recommendations for version control, documentation, or testing.
 
 For more reference material, see :std:doc:`Building and Distributing
-Packages <userguide/index>` in the :ref:`setuptools` docs, but note
+Packages <setuptools: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.
 
@@ -717,7 +717,7 @@ Lastly, if you don't want to install any dependencies at all, you can run:
 
 For more information, see the
 :doc:`Development Mode <setuptools:userguide/development_mode>` section
-of the :doc:`setuptools docs <setuptools>`.
+of the :ref:`setuptools` docs.
 
 .. _`Packaging your project`:
 
diff --git a/source/key_projects.rst b/source/key_projects.rst
@@ -127,6 +127,11 @@ such as :ref:`setuptools` to build distributions, or :ref:`twine` to upload them
 to PyPI. Flit requires Python 3, but you can use it to distribute modules for
 Python 2, so long as they can be imported on Python 3.
 
+The flit package is lifted by `Matthias Bussonnier
+<https://github.com/Carreau>`__ since October 2023 on the `tidelift platform
+<https://tidelift.com/lifter/search/pypi/flit>`__, and funds sent to the PSF and
+earmarked for PyPA usage.
+
 .. _flit-rationale: https://flit.readthedocs.io/en/latest/rationale.html
 
 .. _hatch:
@@ -140,7 +145,7 @@ hatch
 
 Hatch is a unified command-line tool meant to conveniently manage
 dependencies and environment isolation for Python developers. Python
-package developers use Hatch and its build backend Hatchling to
+package developers use Hatch and its :term:`build backend <Build Backend>` Hatchling to
 configure, version, specify dependencies for, and publish packages
 to PyPI. Its plugin system allows for easily extending functionality.
 
diff --git a/source/overview.rst b/source/overview.rst
@@ -167,7 +167,7 @@ Python's native packaging is mostly built for distributing reusable
 code, called libraries, between developers. You can piggyback
 **tools**, or basic applications for developers, on top of Python's
 library packaging, using technologies like
-:doc:`setuptools entry_points <userguide/entry_point>`.
+:doc:`setuptools entry_points <setuptools:userguide/entry_point>`.
 
 Libraries are building blocks, not complete applications. For
 distributing applications, there's a whole new world of technologies
diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst
@@ -27,7 +27,7 @@ table which are not defined by this specification. For tools wishing
 to store their own settings in ``pyproject.toml``, they may use the
 ``[tool]`` table as defined in the
 :ref:`build dependency declaration specification <declaring-build-dependencies>`.
-The lack of a ``[project]`` table implicitly means the build back-end
+The lack of a ``[project]`` table implicitly means the :term:`build backend <Build Backend>`
 will dynamically provide all keys.
 
 The only keys required to be statically defined are:
diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
@@ -43,7 +43,8 @@ The name and version components of the filename MUST match the values stored
 in the metadata contained in the file.
 
 Code that produces a source distribution file MUST give the file a name that matches
-this specification. This includes the ``build_sdist`` hook of a build backend.
+this specification. This includes the ``build_sdist`` hook of a
+:term:`build backend <Build Backend>`.
 
 Code that processes source distribution files MAY recognise source distribution files
 by the ``.tar.gz`` suffix and the presence of precisely *one* hyphen in the filename.
diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst
@@ -1,66 +1,7 @@
-.. _creating-documentation:
+:orphan:
 
+Creating documentation
 ======================
-Creating Documentation
-======================
-
-This section covers the basics of how to create documentation using `Sphinx`_ and
-host the documentation for free in `Read The Docs`_.
-
-.. _Sphinx: https://www.sphinx-doc.org
-.. _Read The Docs: https://readthedocs.org/
-
-Installing Sphinx
------------------
-Use ``pip`` to install Sphinx:
-
-.. tab:: Unix/macOS
-
-    .. code-block:: bash
-
-        python3 -m pip install --upgrade sphinx
-
-.. tab:: Windows
-
-    .. code-block:: bat
-
-        py -m pip install --upgrade sphinx
-
-For other installation methods, see this :doc:`installation guide <sphinx:usage/installation>` by Sphinx.
-
-
-Getting Started With Sphinx
----------------------------
-
-Create a ``docs`` directory inside your project to hold your documentation:
-
-.. code-block:: bash
-
-	cd /path/to/project
-	mkdir docs
-
-Run ``sphinx-quickstart`` inside the ``docs`` directory:
-
-.. code-block:: bash
-
-	cd docs
-	sphinx-quickstart
-
-This sets up a source directory, walks you through some basic configurations, and creates an ``index.rst`` file as well as a ``conf.py`` file.
-
-You can add some information about your project in ``index.rst``, then build them:
-
-.. code-block:: bash
-
-	make html
-
-For more details on the build process, see this `guide`_ by Read The Docs.
-
-.. _guide: https://docs.readthedocs.io/en/latest/intro/import-guide.html
-
-Other Sources
--------------
-
-For a more detailed guide on how to use Sphinx and reStructuredText, please see this `documentation tutorial`_ on Hitchhiker's Guide to Python.
 
-.. _documentation tutorial: https://docs.python-guide.org/writing/documentation/
+This tutorial has been removed since it is not related to packaging and was unmaintained.
+Please see the `Sphinx tutorial <https://www.sphinx-doc.org/en/master/tutorial>`_ instead.
diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst
@@ -11,4 +11,3 @@ topics, see :doc:`/guides/index`.
     installing-packages
     managing-dependencies
     packaging-projects
-    creating-documentation
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
@@ -108,7 +108,7 @@ Choosing a build backend
 
 Tools like :ref:`pip` and :ref:`build` do not actually convert your sources
 into a :term:`distribution package <Distribution Package>` (like a wheel);
-that job is performed by a *build backend*. The build backend determines how
+that job is performed by a :term:`build backend <Build Backend>`. The build backend determines how
 your project will specify its configuration, including metadata (information
 about the project, for example, the name and tags that are displayed on PyPI)
 and input files. Build backends have different levels of functionality, such as
@@ -127,7 +127,7 @@ table for :ref:`metadata <configuring metadata>`.
    management, as well as building, uploading, and installing packages. This
    tutorial uses single-purpose tools that work independently.
 
-The :file:`pyproject.toml` tells "front end" build tools like :ref:`pip` and
+The :file:`pyproject.toml` tells :term:`build frontend <Build Frontend>` tools like :ref:`pip` and
 :ref:`build` which backend to use for your project. Below are some
 examples for common build backends, but check your backend's own documentation
 for more details.
@@ -166,7 +166,7 @@ for more details.
 
 
 The ``requires`` key is a list of packages that are needed to build your package.
-The frontend should install them automatically when building your package.
+The :term:`frontend <Build Frontend>` should install them automatically when building your package.
 Frontends usually run builds in isolated environments, so omitting dependencies
 here may cause build-time errors.
 This should always include your backend's package, and might have other build-time
