diff --git a/.gitignore b/.gitignore index b7f9ac14a9..37a8dabe71 100644 --- a/.gitignore +++ b/.gitignore @@ -24,5 +24,6 @@ src/appendices/command-ref.rst # auto-generated documentation src/plugins/main-loop/built-in src/plugins/install/built-in +src/plugins/xtriggers/built-in src/user-guide/task-implementation/job-runner-handlers src/dictionaries/sentence_case diff --git a/src/plugins/index.rst b/src/plugins/index.rst index 8e78ed3dc5..8d16ab7d3e 100644 --- a/src/plugins/index.rst +++ b/src/plugins/index.rst @@ -12,6 +12,7 @@ The following are "core" plugins maintained by the Cylc team: main-loop/index install/index job-runners/index + xtriggers/index .. warning:: diff --git a/src/plugins/xtriggers/index.rst b/src/plugins/xtriggers/index.rst new file mode 100644 index 0000000000..01e976923b --- /dev/null +++ b/src/plugins/xtriggers/index.rst @@ -0,0 +1,52 @@ +Xtrigger Plugins +====================================== + +Xtrigger plugins allow you to install and use xtriggers without them being +in your ``CYLC_PYTHONPATH``. + + +Built In Plugins +---------------- + +Cylc Flow provides the following xtriggers. + +.. autosummary:: + :toctree: built-in + :template: docstring_only.rst + + cylc.flow.xtriggers.echo + cylc.flow.xtriggers.workflow_state + cylc.flow.xtriggers.xrandom + +.. Note: Autosummary generates files in this directory, these are cleaned + up by `make clean`. + +Developing ``xtrigger`` plugins +------------------------------- + +Cylc uses entry points registered by setuptools to search for xtrigger +plugins. + +Example +^^^^^^^ + +Plugins are registered by registering them with the ``cylc.xtriggers`` +entry points. Each xtrigger is registered individually. + +.. code-block:: ini + :caption: ``setup.cfg`` + + [options.entry_points] + cylc.xtriggers = + foo = my_package.foo:foo + bar = my_package.foo:bar + baz = my_package.baz:baz + +.. code-block:: toml + :caption: ``pyproject.toml`` + + [project.entry-points."cylc.xtriggers"] + foo = "my_package.foo:foo" + bar = "my_package.foo:bar" + baz = "my_package.baz:baz" + diff --git a/src/user-guide/writing-workflows/external-triggers.rst b/src/user-guide/writing-workflows/external-triggers.rst index 0c53feaff3..9f104df747 100644 --- a/src/user-guide/writing-workflows/external-triggers.rst +++ b/src/user-guide/writing-workflows/external-triggers.rst @@ -230,14 +230,17 @@ properties: - they must: - - be defined in a module with the same name as the function; + - be defined in a module with the same name as the function, unless + provided using the ``cylc.xtriggers`` entry point; - be compatible with the same Python version that runs the scheduler (see :ref:`Requirements` for the latest version specification). - they can be located either: - in ``/lib/python/``; - - or anywhere in your ``$CYLC_PYTHONPATH``. + - anywhere in your ``$CYLC_PYTHONPATH``; + - or defined using the ``cylc.xtriggers`` entry point for an installed + package. - they can take arbitrary positional and keyword arguments - workflow and task identity, and cycle point, can be passed to trigger