From 49f52a8598d8a934b07f367a1b3ad87dbe51be5b Mon Sep 17 00:00:00 2001
From: Viicos <65306057+Viicos@users.noreply.github.com>
Date: Thu, 14 Mar 2024 21:06:23 +0100
Subject: [PATCH] Update documentation regarding entry points

Refer to the PyPA packaging guide
Replace references to the deprecated `pkg_resources` docs
---
 docs/source/conf.py                           |  6 +++++-
 docs/source/plugin-development/index.rst      |  7 ++-----
 .../registering-plugins.rst                   | 21 ++++++++++---------
 3 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9b7aa5a4..48f8a524 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -296,7 +296,11 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "packaging": ("https://packaging.python.org/en/latest/", None),
+    "setuptools": ("https://setuptools.pypa.io/en/latest/", None),
+}
 
 extlinks = {
     "issue": ("https://github.com/pycqa/flake8/issues/%s", "#%s"),
diff --git a/docs/source/plugin-development/index.rst b/docs/source/plugin-development/index.rst
index c89e5f0e..82f4a6b6 100644
--- a/docs/source/plugin-development/index.rst
+++ b/docs/source/plugin-development/index.rst
@@ -30,7 +30,8 @@ To get started writing a |Flake8| :term:`plugin` you first need:
 
 Once you've gathered these things, you can get started.
 
-All plugins for |Flake8| must be registered via `entry points`_. In this
+All plugins for |Flake8| must be registered via
+:external:doc:`entry points<specifications/entry-points>`. In this
 section we cover:
 
 - How to register your plugin so |Flake8| can find it
@@ -62,7 +63,3 @@ Here's a tutorial which goes over building an ast checking plugin from scratch:
     registering-plugins
     plugin-parameters
     formatters
-
-
-.. _entry points:
-    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
diff --git a/docs/source/plugin-development/registering-plugins.rst b/docs/source/plugin-development/registering-plugins.rst
index ca740088..e5568b8c 100644
--- a/docs/source/plugin-development/registering-plugins.rst
+++ b/docs/source/plugin-development/registering-plugins.rst
@@ -12,16 +12,15 @@ To register any kind of plugin with |Flake8|, you need:
 
 #. A name for your plugin that will (ideally) be unique.
 
-#. A somewhat recent version of setuptools (newer than 0.7.0 but preferably as
-   recent as you can attain).
-
-|Flake8| relies on functionality provided by setuptools called
-`Entry Points`_. These allow any package to register a plugin with |Flake8|
-via that package's ``setup.py`` file.
+|Flake8| relies on functionality provided by build tools called
+:external:doc:`entry points<specifications/entry-points>`. These allow
+any package to register a plugin with |Flake8| via that package's metadata.
 
 Let's presume that we already have our plugin written and it's in a module
-called ``flake8_example``. We might have a ``setup.py`` that looks something
-like:
+called ``flake8_example``. We will also assume ``setuptools`` is used as a
+:term:`Build Backend`, but be aware that most backends support entry points.
+
+We might have a ``setup.py`` that looks something like:
 
 .. code-block:: python
 
@@ -150,5 +149,7 @@ If your plugin is intended to be opt-in, it can set the attribute
 :ref:`enable-extensions<option-enable-extensions>` with your plugin's entry
 point.
 
-.. _Entry Points:
-    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
+.. seealso::
+
+    The :external:doc:`setuptools user guide <userguide/entry_point>` about
+    entry points.