Add documentation for xtriggers entry_point

src/plugins/index.rst

@@ -12,6 +12,7 @@ The following are "core" plugins maintained by the Cylc team:
    main-loop/index
    install/index
    job-runners/index
+   xtriggers/index
 
 .. warning::
 

src/plugins/xtriggers/index.rst

@@ -0,0 +1,53 @@
+Xtrigger Plugins
+======================================
+
+Xtrigger plugins allow you to install and use xtriggers without them being
+in your ``PYTHONPATH``.
+
+
+Built In Plugins
+----------------
+
+Cylc Flow provides the following xtriggers.
+
+.. autosummary::
+   :toctree: built-in
+   :template: docstring_only.rst
+
+   cylc.flow.xtriggers.echo
+   cylc.flow.xtriggers.wall_clock
+   cylc.flow.xtriggers.workflow_state
+   cylc.flow.xtriggers.xrandom
+
+.. Note: Autosummary generates files in this directory, these are cleaned
+         up by `make clean`.
+
+Developing ``xtrigger`` plugins
+-------------------------------
+
+Cylc uses entry points registered by setuptools to search for xtrigger
+plugins.
+
+Example
+^^^^^^^
+
+Plugins are registered by registering them with the ``cylc.xtriggers``
+entry points. Each xtrigger is registered individually.
+
+.. code-block:: toml
+   :caption: ``setup.cfg``
+
+   [options.entry_points]
+       cylc.xtriggers =
+           foo = my_package.foo:foo
+           bar = my_package.foo:bar
+           faz = my_package.baz:baz
+
+.. code-block:: toml
+   :caption: ``pyproject.toml``
+
+   [project.entry-points."cylc.xtriggers"]
+       foo = my_package.foo:foo
+       bar = my_package.foo:bar
+       faz = my_package.baz:baz
+

src/user-guide/writing-workflows/external-triggers.rst

@@ -230,14 +230,17 @@ properties:
 
 - they must:
 
-  - be defined in a module with the same name as the function;
+  - be defined in a module with the same name as the function, unless
+    provided using the ``cylc.xtriggers`` entry point;
   - be compatible with the same Python version that runs the scheduler
     (see :ref:`Requirements` for the latest version specification).
 
 - they can be located either:
 
   - in ``<workflow-dir>/lib/python/``;
-  - or anywhere in your ``$CYLC_PYTHONPATH``.
+  - anywhere in your ``$CYLC_PYTHONPATH``;
+  - or defined using the ``cylc.xtriggers`` entry point for an installed
+    package.
 
 - they can take arbitrary positional and keyword arguments
 - workflow and task identity, and cycle point, can be passed to trigger