From: Aarni Koskela <akx@iki.fi>
Date: Mon, 13 Jan 2025 11:49:30 +0000 (+0200)
Subject: Refresh docs for extraction method registration
X-Git-Tag: v2.17.0~7^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bb33a7c8fb8cf605b141c485efe73fc0403fc558;p=thirdparty%2Fbabel.git

Refresh docs for extraction method registration
---

diff --git a/docs/messages.rst b/docs/messages.rst
index aeb23123..0f57eb11 100644
--- a/docs/messages.rst
+++ b/docs/messages.rst
@@ -184,12 +184,12 @@ example above.)
 Referencing Extraction Methods
 ------------------------------
 
-To be able to use short extraction method names such as “genshi”, you need to
-have `pkg_resources`_ installed, and the package implementing that extraction
-method needs to have been installed with its meta data (the `egg-info`_).
+Generally, packages publish Babel extractors as Python entry points,
+and so you can use a short name such as “genshi” to refer to them.
 
-If this is not possible for some reason, you need to map the short names to
-fully qualified function names in an extract section in the mapping
+If the package implementing an extraction method has not been installed in a
+way that has kept its entry point mapping intact, you need to map the short
+names to fully qualified function names in an extract section in the mapping
 configuration. For example:
 
 .. code-block:: ini
@@ -202,12 +202,9 @@ configuration. For example:
     [custom: **.ctm]
     some_option = foo
 
-Note that the builtin extraction methods ``python`` and ``ignore`` are available
-by default, even if `pkg_resources`_ is not installed. You should never need to
-explicitly define them in the ``[extractors]`` section.
-
-.. _`egg-info`: http://peak.telecommunity.com/DevCenter/PythonEggs
-.. _`pkg_resources`: http://peak.telecommunity.com/DevCenter/PkgResources
+Note that the builtin extraction methods ``python`` and ``ignore`` are always
+available, and you should never need to explicitly define them in the
+``[extractors]`` section.
 
 
 --------------------------
@@ -240,10 +237,9 @@ need to implement a function that complies with the following interface:
           is the job of the extractor implementation to do the decoding to
           ``unicode`` objects.
 
-Next, you should register that function as an entry point. This requires your
-``setup.py`` script to use `setuptools`_, and your package to be installed with
-the necessary metadata. If that's taken care of, add something like the
-following to your ``setup.py`` script:
+Next, you should register that function as an `entry point`_.
+If using ``setup.py``, add something like the following to your ``setup.py``
+script:
 
 .. code-block:: python
 
@@ -254,6 +250,13 @@ following to your ``setup.py`` script:
         xxx = your.package:extract_xxx
         """,
 
+If using a ``pyproject.toml`` file, add something like the following:
+
+.. code-block:: toml
+
+    [project.entry-points."babel.extractors"]
+    xxx = "your.package:extract_xxx"
+
 That is, add your extraction method to the entry point group
 ``babel.extractors``, where the name of the entry point is the name that people
 will use to reference the extraction method, and the value being the module and