Add documentation for xtriggers entry_point (#671)

Add documentation for xtriggers entry_point

---------

Co-authored-by: Ronnie Dutta <[email protected]>

Author: ColemanTom

.gitignore

@@ -24,5 +24,6 @@ src/appendices/command-ref.rst
 # auto-generated documentation
 src/plugins/main-loop/built-in
 src/plugins/install/built-in
+src/plugins/xtriggers/built-in
 src/user-guide/task-implementation/job-runner-handlers
 src/dictionaries/sentence_case

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,52 @@
+Xtrigger Plugins
+======================================
+
+Xtrigger plugins allow you to install and use xtriggers without them being
+in your ``CYLC_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.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:: ini
+   :caption: ``setup.cfg``
+
+   [options.entry_points]
+       cylc.xtriggers =
+           foo = my_package.foo:foo
+           bar = my_package.foo:bar
+           baz = 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"
+   baz = "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