Merge pull request #6782 from oliver-sanders/docs++

docs: improve abort documentation

Author: wxtim

cylc/flow/cfgspec/globalcfg.py

@@ -220,14 +220,18 @@
         Workflow timeout interval. The timer starts counting down at scheduler
         startup. It resets on workflow restart.
 
+        When the workflow timeout is reached, any configured
+        `[..]workflow timeout handlers` will be called. Additionally, the
+        workflow will shut down if `[..]abort on workflow timeout` is set.
+
         .. seealso::
 
            :ref:`user_guide.scheduler.workflow_events`
 
         .. versionadded:: 8.0.0
     ''',
     'workflow timeout handlers': '''
-        Handlers to run if the workflow timer times out.
+        Handlers to run if the `[..]workflow timeout` is reached.
 
         .. seealso::
 
@@ -237,7 +241,7 @@
     ''',
     'abort on workflow timeout': '''
         Whether the scheduler should shut down immediately with error status if
-        the workflow timer times out.
+        the :cylc:conf:`[..]workflow timeout` is reached.
 
         .. seealso::
 
@@ -259,6 +263,10 @@
     'stall timeout': f'''
         The length of a timer which starts if the scheduler stalls.
 
+        When the stall timeout is reached, any `[..]stall timeout handlers`
+        will be called. Additionally, the workflow will shut down if
+        `[..]abort on stall timeout` is set.
+
         .. seealso::
 
            :ref:`user_guide.scheduler.workflow_events`
@@ -268,7 +276,7 @@
            {REPLACES}``timeout``.
     ''',
     'stall timeout handlers': f'''
-        Handlers to run if the stall timer times out.
+        Handlers to run if the `[..]stall timeout` is reached.
 
         .. seealso::
 
@@ -280,7 +288,7 @@
     ''',
     'abort on stall timeout': f'''
         Whether the scheduler should shut down immediately with error status if
-        the stall timer times out.
+        the `[..]stall timeout` is reached.
 
         .. seealso::
 
@@ -294,6 +302,10 @@
         Scheduler inactivity timeout interval. The timer resets when any
         workflow activity occurs.
 
+        When the inactivity timeout is reached, any
+        `[..]inactivity timeout handlers` will be called. Additionally, the
+        workflow will shut down if `[..]abort on inactivity timeout` is set.
+
         .. seealso::
 
            :ref:`user_guide.scheduler.workflow_events`
@@ -303,7 +315,7 @@
            {REPLACES} ``inactivity``.
     ''',
     'inactivity timeout handlers': f'''
-        Handlers to run if the inactivity timer times out.
+        Handlers to run if the `[..]inactivity timeout` is reached.
 
         .. seealso::
 
@@ -315,7 +327,7 @@
     ''',
     'abort on inactivity timeout': f'''
         Whether the scheduler should shut down immediately with error status if
-        the inactivity timer times out.
+        the `[..]inactivity timeout` is reached.
 
         .. seealso::