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 1/4] 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`. 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`. 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` 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 ` about + entry points. From 350f2545fd3ec75640a1605e4995a2f921e8b38b Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Sun, 17 Mar 2024 08:56:07 +0100 Subject: [PATCH 2/4] Use explicit external references --- docs/source/plugin-development/index.rst | 2 +- .../plugin-development/registering-plugins.rst | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/source/plugin-development/index.rst b/docs/source/plugin-development/index.rst index 82f4a6b6..9b38fe26 100644 --- a/docs/source/plugin-development/index.rst +++ b/docs/source/plugin-development/index.rst @@ -31,7 +31,7 @@ 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 -:external:doc:`entry points`. In this +:external+packaging:doc:`entry points`. In this section we cover: - How to register your plugin so |Flake8| can find it diff --git a/docs/source/plugin-development/registering-plugins.rst b/docs/source/plugin-development/registering-plugins.rst index e5568b8c..41c34e0a 100644 --- a/docs/source/plugin-development/registering-plugins.rst +++ b/docs/source/plugin-development/registering-plugins.rst @@ -13,12 +13,14 @@ To register any kind of plugin with |Flake8|, you need: #. A name for your plugin that will (ideally) be unique. |Flake8| relies on functionality provided by build tools called -:external:doc:`entry points`. These allow -any package to register a plugin with |Flake8| via that package's metadata. +:external+packaging:doc:`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 +:external+packaging:term:`Build Backend`, but be aware that most backends called ``flake8_example``. We will also assume ``setuptools`` is used as a -:term:`Build Backend`, but be aware that most backends support entry points. +support entry points. We might have a ``setup.py`` that looks something like: @@ -151,5 +153,5 @@ point. .. seealso:: - The :external:doc:`setuptools user guide ` about - entry points. + The :external+setuptools:doc:`setuptools user guide ` + about entry points. From ba0f56610adbd4d8733772ce1c63efcab1b70079 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Sun, 17 Mar 2024 08:56:07 +0100 Subject: [PATCH 3/4] Use explicit external references --- docs/source/plugin-development/registering-plugins.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/plugin-development/registering-plugins.rst b/docs/source/plugin-development/registering-plugins.rst index 41c34e0a..aac87e87 100644 --- a/docs/source/plugin-development/registering-plugins.rst +++ b/docs/source/plugin-development/registering-plugins.rst @@ -20,6 +20,7 @@ metadata. Let's presume that we already have our plugin written and it's in a module :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: From 6659b213c9aa8fa49235e13a365fcd34f58cbc6b Mon Sep 17 00:00:00 2001 From: Ian Stapleton Cordasco Date: Mon, 18 Mar 2024 10:43:13 -0500 Subject: [PATCH 4/4] Fix toctree ordering in index Also fix line-length issue in PR --- docs/source/plugin-development/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/plugin-development/index.rst b/docs/source/plugin-development/index.rst index 9b38fe26..90889429 100644 --- a/docs/source/plugin-development/index.rst +++ b/docs/source/plugin-development/index.rst @@ -55,6 +55,8 @@ Here's a tutorial which goes over building an ast checking plugin from scratch: +Detailed Plugin Development Documentation +========================================= .. toctree:: :caption: Plugin Developer Documentation