From fc6d7a1d4e4796c2c9179ac11e6b9b449f4911a3 Mon Sep 17 00:00:00 2001 From: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> Date: Wed, 22 Nov 2023 16:58:26 +0000 Subject: [PATCH] Autodoc built-in xtrigger functions --- src/conf.py | 4 ++++ .../writing-workflows/external-triggers.rst | 14 +++++++------- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/src/conf.py b/src/conf.py index b18b4a693b..8df72bdf76 100644 --- a/src/conf.py +++ b/src/conf.py @@ -109,6 +109,10 @@ autosummary_generate_overwrite = True autosummary_imported_members = False +# Autodoc type hints can look very messy if they are included in the signature, +# so we only include them in the description instead: +autodoc_typehints = 'description' + # Mapping to other Sphinx projects we want to import references from. # NOTE: To search available references, use: # $ python -m sphinx.ext.intersphinx /objects.inv | less diff --git a/src/user-guide/writing-workflows/external-triggers.rst b/src/user-guide/writing-workflows/external-triggers.rst index 167e497057..01988a3c48 100644 --- a/src/user-guide/writing-workflows/external-triggers.rst +++ b/src/user-guide/writing-workflows/external-triggers.rst @@ -62,6 +62,11 @@ in :ref:`ClockTriggerTasks`. Clock triggers, unlike other trigger functions, are executed synchronously in the main process. The clock trigger function signature looks like this: +.. + NOTE: don't use autofunction here because cylc.flow.xtriggers.wall_clock + has a different signature, and instead there is special handling + in XtriggerManager + .. code-block:: python wall_clock(offset=None) @@ -130,10 +135,7 @@ tasks off of remote task statuses or messages in other workflows. The workflow state trigger function signature looks like this: -.. code-block:: python - - workflow_state(workflow, task, point, offset=None, status='succeeded', - message=None, cylc_run_dir=None, debug=False) +.. autofunction:: cylc.flow.xtriggers.workflow_state.workflow_state The first three arguments are compulsory; they single out the target workflow name (``workflow``) task name (``task``) and cycle point @@ -344,9 +346,7 @@ time (useful for testing the effect of a long-running trigger function - which should be avoided) and has a configurable random chance of success. The function signature is: -.. code-block:: python - - xrandom(percent, secs=0, _=None, debug=False) +.. autofunction:: cylc.flow.xtriggers.xrandom.xrandom The ``percent`` argument sets the odds of success in any given call; ``secs`` is the number of seconds to sleep before returning; and the