event handlers: improve docs

Author: oliver-sanders

src/glossary.rst

@@ -1654,8 +1654,6 @@ Glossary
       WARNING messages from a task :term:`job`.
 
 
-   .. TODO cylc-flow cfgspec/workflow.py references "event handlers" plural
-
    handler
    event handler
    event handlers
@@ -1671,9 +1669,8 @@ Glossary
 
       .. seealso::
 
-         - :cylc:conf:`task events <[runtime][<namespace>][events]>`
-         - :cylc:conf:`workflow events <[scheduler][events]>`
-         - :ref:`Cylc User Guide <EventHandling>`
+         - :ref:`user_guide.scheduler.workflow_event_handling`
+         - :ref:`user_guide.runtime.task_event_handling`
 
 
    runahead limit

src/installation.rst

@@ -250,6 +250,7 @@ To do so create a symbolic link to the wrapper, for each of these commands:
    ln -s cylc rosie
    ln -s cylc isodatetime
 
+
 Configuration
 -------------
 
@@ -259,7 +260,7 @@ However, many things may need to be configured, e.g:
 
 * :ref:`AdminGuide.PlatformConfigs` (jobs hosts, runners, etc)
 * :ref:`Scheduler Hosts<Submitting Workflows To a Pool Of Hosts>`
-* :ref:`Default Event Handlers<EventHandlers>`
+* :ref:`Default Event Handlers<user_guide.runtime.task_event_handling.general_event_handlers>`.
 
 Cylc Flow
 ^^^^^^^^^

src/user-guide/task-implementation/job-scripts.rst

@@ -127,7 +127,8 @@ execution has started, succeeded, or failed. Custom messages can also be sent
 by the same mechanism, with various severity levels. These can be used to
 trigger other tasks off specific task outputs (see :ref:`MessageTriggers`), or
 to trigger execution of event handlers by the scheduler (see
-:ref:`EventHandling`), or just to write information to the scheduler log.
+:ref:`user_guide.runtime.task_event_handling`)
+or just to write information to the scheduler log.
 
 .. cylc-scope:: global.cylc[platforms][<platform name>]
 

src/user-guide/writing-workflows/runtime.rst

@@ -567,22 +567,25 @@ task ``whizz`` downstream. The scheduler will then stall with
            script = "sleep 10"
 
 
-.. _EventHandling:
+.. _user_guide.runtime.task_event_handling:
 
-Event Handling
---------------
+Task Event Handling
+-------------------
 
-.. seealso::
+Task event handlers allow configured commands to run when task events occur.
 
-  * Task events :cylc:conf:`[runtime][<namespace>][events]`
-  * Workflow events :cylc:conf:`[scheduler][events]`
+.. note::
 
-.. cylc-scope:: flow.cylc[runtime][<namespace>]
+   Cylc supports workflow events e.g. ``startup`` and ``shutdown``
+   and task events e.g. ``submitted`` and ``failed``.
 
-Custom *event handler* scripts can be called when certain workflow and task
-events occur. Event handlers can be used to send a message, raise an alarm, or
-whatever you like. They can even call ``cylc`` commands to intervene in the
-workflow.
+   See also :ref:`user_guide.scheduler.workflow_event_handling`.
+
+Event handlers can be used to send a message, raise an alarm, or whatever you
+like. They can even call ``cylc`` commands to intervene in the workflow.
+
+Task event handlers are configured by
+:cylc:conf:`flow.cylc[runtime][<namespace>][events]`.
 
 .. note::
 
@@ -596,7 +599,7 @@ They should return quickly to avoid tying up the scheduler process pool -
 see :ref:`Managing External Command Execution`.
 
 
-.. cylc-scope::
+.. _user_guide.runtime.task_event_handling.event_specific_handlers:
 
 Event-Specific Handlers
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -634,18 +637,40 @@ can be:
 Values should be a list of commands, command lines, or command line templates
 (see below) to call if the specified event is triggered.
 
+
+.. _user_guide.runtime.task_event_handling.general_event_handlers:
+
 General Event Handlers
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Alternatively you can configure ``handler events`` and ``handlers``
-under :cylc:conf:`[runtime][<namespace>][events]`, where the former is a list
-of events (as above), and the latter a list of commands, command lines, lines
-or command line templates (see below) to call if any of the specified events
-are triggered.
+.. cylc-scope:: flow.cylc[runtime][<namespace>][events]
+
+Alternatively you can configure a list of generic event :cylc:conf:`handlers` to be run
+for configured :cylc:conf:`handler events`.
+
+:cylc:conf:`handler events`
+   A list of events which may include any of the above
+   events (e.g. ``submission failed`` or ``warning``) or
+   any of a task's :term:`custom outputs <custom output>`.
+:cylc:conf:`handlers`
+   A list of commands to be run for these events.
+   Information about the event can be provided using
+   :ref:`user_guide.runtime.event_handlers.task_event_handling.template_variables`.
+
+Example:
+
+.. code-block:: cylc
+
+   handlers = """
+      my-handler %(event)s %(workflow)s,
+      echo %(workflow)s-%(event)s >> my-log-file
+   """
+   handler events = submission failed, failed, warning, my-custom-output
 
 .. cylc-scope::
 
-.. _task_event_template_variables:
+
+.. _user_guide.runtime.event_handlers.task_event_handling.template_variables:
 
 Task Event Template Variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

src/user-guide/writing-workflows/scheduler.rst

@@ -8,20 +8,27 @@ Many of these configurations can also be defined at the site or user level in
 the :cylc:conf:`global.cylc[scheduler]` section where it applies to all
 workflows.
 
-.. _EventHandlers:
 
-Event handlers
---------------
+.. _user_guide.scheduler.workflow_event_handling:
+
+Workflow Event Handling
+-----------------------
+
+Workflow event handlers allow configured commands to run when workflow events
+occur.
 
 .. note::
 
-   Workflow event handlers are configured by:
+   Cylc supports workflow events e.g. ``startup`` and ``shutdown``
+   and task events e.g. ``submitted`` and ``failed``.
+
+   See also :ref:`user_guide.runtime.task_event_handling`.
+
+Workflow event handlers are configured by:
 
-   * :cylc:conf:`flow.cylc[scheduler][events]`
-   * :cylc:conf:`global.cylc[scheduler][events]`
+* :cylc:conf:`flow.cylc[scheduler][events]` (per workflow)
+* :cylc:conf:`global.cylc[scheduler][events]` (user/site defaults)
 
-Workflow event handlers allow configurable actions to be performed when
-workflow events occur.
 
 Workflow Events
 ^^^^^^^^^^^^^^^