Improve xtrigger plugins docs

src/plugins/xtriggers/index.rst

@@ -1,8 +1,16 @@
 Xtrigger Plugins
 ======================================
 
-Xtrigger plugins allow you to install and use xtriggers without them being
-in your ``CYLC_PYTHONPATH``.
+.. versionadded:: 8.3
+
+   Xtrigger plugins allow you to install and use
+   :ref:`xtriggers <Section External Triggers>` without them being
+   in ``<workflow-dir>/lib/python/`` or ``$CYLC_PYTHONPATH``.
+
+.. seealso::
+
+   * :ref:`Built-in Clock Triggers`
+   * :ref:`Built-in Workflow State Triggers`
 
 
 Built In Plugins
@@ -26,20 +34,37 @@ Cylc Flow provides the following xtriggers.
 Developing ``xtrigger`` plugins
 -------------------------------
 
-Cylc uses entry points registered by setuptools to search for xtrigger
-plugins.
+Cylc uses the ``cylc.xtriggers`` entry point registered by setuptools to search
+for xtrigger plugins. Each xtrigger is registered individually.
 
 Example
 ^^^^^^^
 
-Plugins are registered by registering them with the ``cylc.xtriggers``
-entry points. Each xtrigger is registered individually.
+Consider a package called ``my_package`` with the following structure:
+
+.. code-block:: python
+   :caption: ``my_package/foo.py``
+
+   def foo():
+       ...
+
+   def bar():
+       ...
+
+.. code-block:: python
+   :caption: ``my_package/baz.py``
+
+   def baz():
+       ...
+
+These xtriggers can be registered in the package's ``setup.cfg`` or
+``pyproject.toml`` file.
 
 .. code-block:: ini
    :caption: ``setup.cfg``
 
    [options.entry_points]
-       cylc.xtriggers =
+   cylc.xtriggers =
        foo = my_package.foo
        bar = my_package.foo
        baz = my_package.baz

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

@@ -34,13 +34,11 @@ broker.
 
 Cylc has several built-in external trigger functions:
 
-- clock triggers - see :ref:`Built-in Clock Triggers`
-- inter-workflow triggers - see :ref:`Built-in Workflow State Triggers`
+- :ref:`Built-in Clock Triggers`
+- :ref:`Built-in Workflow State Triggers`
 
 Trigger functions are normal Python functions, with certain constraints as
-described below in:
-
-- custom trigger functions - see :ref:`Custom Trigger Functions`
+described below in :ref:`Custom Trigger Functions`.
 
 External triggers are configured in the
 :cylc:conf:`flow.cylc[scheduling][xtriggers]` section.
@@ -240,12 +238,7 @@ properties:
   - In ``<workflow-dir>/lib/python/``;
   - Anywhere in your ``$CYLC_PYTHONPATH``;
   - Defined using the ``cylc.xtriggers`` entry point for an installed
-    package.
-
-.. seealso::
-
-   :ref:`developing.xtrigger.plugins` for more information on writing
-   xtrigger plugins.
+    package - see :ref:`developing.xtrigger.plugins`
 
 - They can take arbitrary positional and keyword arguments
 - Workflow and task identity, and cycle point, can be passed to trigger
@@ -255,9 +248,9 @@ properties:
 - If a trigger function depends on files or directories (for example)
   that might not exist when the function is first called, just return
   unsatisfied until everything required does exist.
-- The module containing the xtrigger function may also contain a "validate"
+- The module containing the xtrigger function may also contain a ``validate``
   function taking arguments ``args``, ``kwargs`` and ``signature``, and
-  raising ``cylc.flow.exceptions import WorkflowConfigError`` if validation
+  raising :py:exc:`cylc.flow.exceptions.WorkflowConfigError` if validation
   fails. See :ref:`xrandom.validate` for an example of a validate function.
 
 .. note::
@@ -377,28 +370,20 @@ An example xrandom trigger workflow:
 Validation example using xrandom
 """"""""""""""""""""""""""""""""
 
-The xrandom xtrigger module might also contain a ``validate`` function.
+The ``xrandom`` xtrigger module contains a ``validate`` function.
 
-This will be run on the inputs to an xtrigger, and should raise
-a ``WorkflowConfigError`` with a meaningful description if a condition
-is not met.
+This will be run on the inputs to the xtrigger when calling
+``cylc validate`` or before the workflow starts, and should raise a
+:py:exc:`cylc.flow.exceptions.WorkflowConfigError`
+with a meaningful description if a condition is not met.
+
+A simplified example looks like this:
 
 .. code-block:: python
 
    from cylc.flow.exceptions import WorkflowConfigError
 
-   def validate(args: List, kwargs: Dict, signature: str) -> None:
-       # Total number of args & kwargs makes sense:
-       totalargs = len(args) + len(kwargs)
-       if totalargs < 1 or totalargs > 4:
-           raise WorkflowConfigError(
-               f'{signature} xtrigger should have between 1 and 4 arguments')
-
-       # Check whether we have a percentage argument:
-       if not args and not 'percent' in kwargs:
-           raise WorkflowConfigError(
-               f'{signature} xtrigger should have a percentage argument')
-
+   def validate(args: List[str], kwargs: Dict[str, Any], signature: str) -> None:
        # Check that percentage is a reasonable value:
        percentage = args[0] if args else kwargs['percentage']
        if (
@@ -410,6 +395,18 @@ is not met.
                f'{signature} xtrigger percentage argument'
                f' must be a number between 0 and 100, not {percentage}')
 
+See below for a link to the full ``validate`` function:
+
+.. autofunction:: cylc.flow.xtriggers.xrandom.validate
+
+.. tip::
+
+   The arguments you call the xtrigger function with are automatically
+   validated against the function signature, so you don't necessarily need
+   to check for the presence of arguments or their types in the validate
+   function. However, you may want to check that the values are of the correct
+   type or within a certain range.
+
 
 .. _Current Trigger Function Limitations: