Skip to content

Commit

Permalink
Merge pull request #1923 from Viicos/entry-points-docs
Browse files Browse the repository at this point in the history
Update documentation regarding entry points
  • Loading branch information
sigmavirus24 authored Mar 19, 2024
2 parents 5c52d75 + 6659b21 commit 33e5083
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 16 deletions.
6 changes: 5 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
Expand Down
9 changes: 4 additions & 5 deletions docs/source/plugin-development/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
24 changes: 14 additions & 10 deletions docs/source/plugin-development/registering-plugins.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

0 comments on commit 33e5083

Please sign in to comment.