Skip to content

Commit df72a56

Browse files
oliver-sandersoliver-sanders
authored
Merge pull request #6899 from MetRonnie/events-docs
Improve events docs
2 parents 58690dd + ee7a333 commit df72a56

File tree

3 files changed

+51
-45
lines changed

3 files changed

+51
-45
lines changed

‎cylc/flow/cfgspec/globalcfg.py‎

Lines changed: 32 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -171,9 +171,11 @@
171171
Configure :term:`event handlers` that run when certain workflow
172172
events occur.
173173
174-
This section configures *workflow* event handlers; see
175-
:cylc:conf:`flow.cylc[runtime][<namespace>][events]` for *task* event
176-
handlers.
174+
.. admonition:: Not to be confused with
175+
:class: tip
176+
177+
For *task* events, see
178+
:cylc:conf:`flow.cylc[runtime][<namespace>][events]`.
177179
178180
Event handlers can be held in the workflow ``bin/`` directory,
179181
otherwise it is up to you to ensure their location is in ``$PATH``
@@ -194,7 +196,7 @@
194196
195197
.. seealso::
196198
197-
:ref:`user_guide.scheduler.workflow_events`
199+
:ref:`user_guide.scheduler.workflow_events.list`
198200
''',
199201
'options': WorkflowEventHandler.EVENTS.copy(),
200202
'depr_options': WorkflowEventHandler.EVENTS_DEPRECATED.copy(),
@@ -203,6 +205,10 @@
203205
'desc': '''
204206
Specify the workflow events for which notification emails should
205207
be sent.
208+
209+
.. seealso::
210+
211+
:ref:`user_guide.scheduler.workflow_events.list`
206212
''',
207213
'options': WorkflowEventHandler.EVENTS.copy(),
208214
'depr_options': WorkflowEventHandler.EVENTS_DEPRECATED.copy(),
@@ -546,7 +552,10 @@
546552
TASK_EVENTS_DESCR = '''
547553
Configure the task event handling system.
548554
549-
See also :cylc:conf:`flow.cylc[scheduler][events]` for *workflow* events.
555+
.. admonition:: Not to be confused with
556+
:class: tip
557+
558+
For *workflow* events, see :cylc:conf:`flow.cylc[scheduler][events]`.
550559
551560
Task :term:`event handlers` are scripts to run when task events occur.
552561
@@ -576,26 +585,16 @@
576585
For more information, see
577586
:ref:`user_guide.runtime.task_event_handling`.
578587
579-
For workflow events, see
580-
:ref:`user_guide.scheduler.workflow_event_handling`.
581-
582588
Example::
583589
584590
echo %(event)s occurred in %(workflow)s >> my-log-file
585591
586592
''',
587-
'execution timeout': '''
588-
If a task has not finished after the specified interval, the execution
589-
timeout event handler(s) will be called.
590-
''',
591593
'handler events': '''
592594
A list of events for which :cylc:conf:`[..]handlers` are run.
593595
594-
Specify the events for which the general task event handlers
595-
:cylc:conf:`flow.cylc[runtime][<namespace>][events]handlers`
596-
should be invoked.
597-
598-
See :ref:`user_guide.runtime.task_event_handling` for more information.
596+
See :ref:`user_guide.runtime.task_event_handling.list` for valid
597+
events.
599598
600599
Example::
601600
@@ -613,15 +612,22 @@
613612
PT10S, PT1M, PT5M
614613
''',
615614
'mail events': '''
616-
Specify the events for which notification emails should be sent.
615+
A list of events for which notification emails should be sent.
616+
617+
See :ref:`user_guide.runtime.task_event_handling.list` for valid
618+
events.
617619
618620
Example::
619621
620622
submission failed, failed
621623
''',
624+
'execution timeout': '''
625+
If a task has not finished after the specified interval, any configured
626+
execution timeout event handler(s) will be called.
627+
''',
622628
'submission timeout': '''
623-
If a task has not started after the specified interval, the submission
624-
timeout event handler(s) will be called.
629+
If a task has not started after the specified interval, any configured
630+
submission timeout event handler(s) will be called.
625631
'''
626632
}
627633

@@ -2004,12 +2010,6 @@ def default_for(
20042010
TASK_EVENTS_DESCR, "[runtime][<namespace>][events]", section=True
20052011
) + "\n\n" + ".. versionadded:: 8.0.0"
20062012
)):
2007-
Conf('execution timeout', VDR.V_INTERVAL, desc=(
2008-
default_for(
2009-
TASK_EVENTS_SETTINGS['execution timeout'],
2010-
"[runtime][<namespace>][events]execution timeout"
2011-
)
2012-
))
20132013
Conf('handlers', VDR.V_STRING_LIST, desc=(
20142014
default_for(
20152015
TASK_EVENTS_SETTINGS['handlers'],
@@ -2034,6 +2034,12 @@ def default_for(
20342034
"[runtime][<namespace>][events]mail events"
20352035
)
20362036
))
2037+
Conf('execution timeout', VDR.V_INTERVAL, desc=(
2038+
default_for(
2039+
TASK_EVENTS_SETTINGS['execution timeout'],
2040+
"[runtime][<namespace>][events]execution timeout"
2041+
)
2042+
))
20372043
Conf('submission timeout', VDR.V_INTERVAL, desc=(
20382044
default_for(
20392045
TASK_EVENTS_SETTINGS['submission timeout'],

‎cylc/flow/cfgspec/workflow.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1646,12 +1646,6 @@ def get_script_common_text(this: str, example: Optional[str] = None):
16461646
with Conf('events', desc=(
16471647
global_default(TASK_EVENTS_DESCR, "[task events]")
16481648
)):
1649-
Conf('execution timeout', VDR.V_INTERVAL, desc=(
1650-
global_default(
1651-
TASK_EVENTS_SETTINGS['execution timeout'],
1652-
"[task events]execution timeout"
1653-
)
1654-
))
16551649
Conf('handlers', VDR.V_STRING_LIST, None, desc=(
16561650
global_default(
16571651
TASK_EVENTS_SETTINGS['handlers'],
@@ -1676,6 +1670,12 @@ def get_script_common_text(this: str, example: Optional[str] = None):
16761670
"[task events]mail events"
16771671
)
16781672
))
1673+
Conf('execution timeout', VDR.V_INTERVAL, desc=(
1674+
global_default(
1675+
TASK_EVENTS_SETTINGS['execution timeout'],
1676+
"[task events]execution timeout"
1677+
)
1678+
))
16791679
Conf('submission timeout', VDR.V_INTERVAL, desc=(
16801680
global_default(
16811681
TASK_EVENTS_SETTINGS['submission timeout'],

‎tests/functional/cylc-config/00-simple/section2.stdout‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,11 @@
4343
retrieve job logs max size =
4444
retrieve job logs retry delays =
4545
[[[events]]]
46-
execution timeout =
4746
handlers =
4847
handler events =
4948
handler retry delays =
5049
mail events =
50+
execution timeout =
5151
submission timeout =
5252
expired handlers =
5353
late offset =
@@ -122,11 +122,11 @@
122122
retrieve job logs max size =
123123
retrieve job logs retry delays =
124124
[[[events]]]
125-
execution timeout =
126125
handlers =
127126
handler events =
128127
handler retry delays =
129128
mail events =
129+
execution timeout =
130130
submission timeout =
131131
expired handlers =
132132
late offset =
@@ -201,11 +201,11 @@
201201
retrieve job logs max size =
202202
retrieve job logs retry delays =
203203
[[[events]]]
204-
execution timeout =
205204
handlers =
206205
handler events =
207206
handler retry delays =
208207
mail events =
208+
execution timeout =
209209
submission timeout =
210210
expired handlers =
211211
late offset =
@@ -282,11 +282,11 @@
282282
retrieve job logs max size =
283283
retrieve job logs retry delays =
284284
[[[events]]]
285-
execution timeout =
286285
handlers =
287286
handler events =
288287
handler retry delays =
289288
mail events =
289+
execution timeout =
290290
submission timeout =
291291
expired handlers =
292292
late offset =
@@ -362,11 +362,11 @@
362362
retrieve job logs max size =
363363
retrieve job logs retry delays =
364364
[[[events]]]
365-
execution timeout =
366365
handlers =
367366
handler events =
368367
handler retry delays =
369368
mail events =
369+
execution timeout =
370370
submission timeout =
371371
expired handlers =
372372
late offset =
@@ -442,11 +442,11 @@
442442
retrieve job logs max size =
443443
retrieve job logs retry delays =
444444
[[[events]]]
445-
execution timeout =
446445
handlers =
447446
handler events =
448447
handler retry delays =
449448
mail events =
449+
execution timeout =
450450
submission timeout =
451451
expired handlers =
452452
late offset =
@@ -522,11 +522,11 @@
522522
retrieve job logs max size =
523523
retrieve job logs retry delays =
524524
[[[events]]]
525-
execution timeout =
526525
handlers =
527526
handler events =
528527
handler retry delays =
529528
mail events =
529+
execution timeout =
530530
submission timeout =
531531
expired handlers =
532532
late offset =
@@ -602,11 +602,11 @@
602602
retrieve job logs max size =
603603
retrieve job logs retry delays =
604604
[[[events]]]
605-
execution timeout =
606605
handlers =
607606
handler events =
608607
handler retry delays =
609608
mail events =
609+
execution timeout =
610610
submission timeout =
611611
expired handlers =
612612
late offset =
@@ -682,11 +682,11 @@
682682
retrieve job logs max size =
683683
retrieve job logs retry delays =
684684
[[[events]]]
685-
execution timeout =
686685
handlers =
687686
handler events =
688687
handler retry delays =
689688
mail events =
689+
execution timeout =
690690
submission timeout =
691691
expired handlers =
692692
late offset =
@@ -762,11 +762,11 @@
762762
retrieve job logs max size =
763763
retrieve job logs retry delays =
764764
[[[events]]]
765-
execution timeout =
766765
handlers =
767766
handler events =
768767
handler retry delays =
769768
mail events =
769+
execution timeout =
770770
submission timeout =
771771
expired handlers =
772772
late offset =
@@ -842,11 +842,11 @@
842842
retrieve job logs max size =
843843
retrieve job logs retry delays =
844844
[[[events]]]
845-
execution timeout =
846845
handlers =
847846
handler events =
848847
handler retry delays =
849848
mail events =
849+
execution timeout =
850850
submission timeout =
851851
expired handlers =
852852
late offset =
@@ -922,11 +922,11 @@
922922
retrieve job logs max size =
923923
retrieve job logs retry delays =
924924
[[[events]]]
925-
execution timeout =
926925
handlers =
927926
handler events =
928927
handler retry delays =
929928
mail events =
929+
execution timeout =
930930
submission timeout =
931931
expired handlers =
932932
late offset =
@@ -1002,11 +1002,11 @@
10021002
retrieve job logs max size =
10031003
retrieve job logs retry delays =
10041004
[[[events]]]
1005-
execution timeout =
10061005
handlers =
10071006
handler events =
10081007
handler retry delays =
10091008
mail events =
1009+
execution timeout =
10101010
submission timeout =
10111011
expired handlers =
10121012
late offset =

0 commit comments

Comments
 (0)