Merge pull request #1923 from Viicos/entry-points-docs

Update documentation regarding entry points

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"),

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+packaging:doc:`entry points<specifications/entry-points>`. In this
 section we cover:
 
 - How to register your plugin so |Flake8| can find it
@@ -54,6 +55,8 @@ Here's a tutorial which goes over building an ast checking plugin from scratch:
         <iframe src="https://www.youtube.com/embed/ot5Z4KQPBL8" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
     </div>
 
+Detailed Plugin Development Documentation
+=========================================
 
 .. toctree::
     :caption: Plugin Developer Documentation
@@ -62,7 +65,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

docs/source/plugin-development/registering-plugins.rst

@@ -12,16 +12,18 @@ 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+packaging: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:
+:external+packaging:term:`Build Backend`, but be aware that most backends
+called ``flake8_example``. We will also assume ``setuptools`` is used as a
+:external+packaging: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 +152,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+setuptools:doc:`setuptools user guide <userguide/entry_point>`
+    about entry points.