Xtriggers: improve docs (#686)

Author: wxtim

.github/workflows/test.yml

@@ -79,7 +79,7 @@ jobs:
 
       - name: build & test
         run: |
-          make html spelling linkcheck doctest \
+          make html spelling linkcheck \
             SPHINXOPTS='-Wn --keep-going' FORCE_COLOR=true
 
       - name: debug sphinx failure

Makefile

@@ -20,6 +20,7 @@ clean:
 	# remove auto-generated content
 	rm -rf src/plugins/main-loop/built-in
 	rm -rf src/plugins/install/built-in
+	rm -rf src/plugins/xtriggers/built-in
 	rm -rf src/user-guide/task-implementation/job-runner-handlers
 
 watch: clean

README.md

@@ -183,7 +183,7 @@ allows it to pick up changes to autodocumented items in the source code.
 
 ```console
 # note: -W tells Sphinx to fail on warnings
-$ make html linkcheck doctest SPHINXOPTS='-W'
+$ make html linkcheck SPHINXOPTS='-W'
 ```
 
 ### Deploying

bin/version

@@ -27,7 +27,6 @@ from pkg_resources import parse_version
 DUMMY_FORMATS = [
     'doctrees',
     'linkcheck',
-    'doctest',
     'coverage'
 ]
 

src/conf.py

@@ -34,7 +34,6 @@
     # sphinx built-in extensions
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.doctest',
     'sphinx.ext.graphviz',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
@@ -111,6 +110,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 <url>/objects.inv | less

src/dictionaries/words

@@ -46,6 +46,7 @@ filesystem
 filesystems
 fillchar
 foo
+fpath
 freeform
 fullmatch
 globals
@@ -129,6 +130,7 @@ py
 pythonically
 queueing
 qux
+randint
 rc
 refactor
 regex
@@ -148,6 +150,7 @@ ret
 retrigger
 retriggered
 retriggering
+rmtree
 roadmap
 ruleset
 rulesets
@@ -156,10 +159,12 @@ runnable
 runtime
 schd
 screenshot
+secs
 setup
 setups
 shebang
 shutdown
+shutil
 situ
 speedup
 ssh
@@ -186,6 +191,7 @@ symlink
 symlinked
 symlinking
 symlinks
+sys
 taskdef
 templated
 templating
@@ -195,6 +201,7 @@ timeouts
 timestep
 timezone
 timezones
+tuple
 uiserver
 unpaused
 unpausing
@@ -209,6 +216,7 @@ vs
 wallclock
 websocket
 websockets
+whitelist
 whitelisting
 whitespace
 workflow

src/plugins/xtriggers/index.rst

@@ -1,52 +1,70 @@
 Xtrigger Plugins
 ======================================
 
-Xtrigger plugins allow you to install and use xtriggers without them being
-in your ``CYLC_PYTHONPATH``.
+.. versionadded:: 8.3
 
+   Xtrigger plugins allow you to install and use
+   :ref:`xtriggers <Section External Triggers>` without them being
+   in ``<workflow-dir>/lib/python/`` or ``$CYLC_PYTHONPATH``.
 
-Built In Plugins
-----------------
+.. seealso::
 
-Cylc Flow provides the following xtriggers.
+   * :ref:`Built-in Clock Triggers`
+   * :ref:`Built-in Workflow State Triggers`
+   * :ref:`Built-in Toy 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:
 
 Developing ``xtrigger`` plugins
 -------------------------------
 
-Cylc uses entry points registered by setuptools to search for xtrigger
-plugins.
+Cylc uses the ``cylc.xtriggers`` entry point registered by setuptools to search
+for xtrigger plugins. Each xtrigger is registered individually.
 
 Example
 ^^^^^^^
 
-Plugins are registered by registering them with the ``cylc.xtriggers``
-entry points. Each xtrigger is registered individually.
+Consider a package called ``my_package`` with the following structure:
+
+.. code-block:: python
+   :caption: ``my_package/foo.py``
+
+   def foo():
+       ...
+
+   def bar():
+       ...
+
+.. code-block:: python
+   :caption: ``my_package/baz.py``
+
+   def baz():
+       ...
+
+These xtriggers can be registered in the package's ``setup.cfg`` or
+``pyproject.toml`` file.
 
 .. 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
+   cylc.xtriggers =
+       foo = my_package.foo
+       bar = my_package.foo
+       baz = my_package.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"
+   foo = "my_package.foo"
+   bar = "my_package.foo"
+   baz = "my_package.baz"
+
+.. tip::
+
+   It is recommended to implement only one xtrigger per module. This allows
+   you to write a ``validate`` function for each xtrigger - see
+   :ref:`user-guide.xtrigger-validation-functions`.
 

src/tutorial/furthertopics/clock-triggered-tasks.rst

@@ -14,7 +14,8 @@ Clock-triggering effectively enables us to tether the "cycle time" to the
 .. note::
 
    Clock triggers are :ref:`Section External Triggers`. They differ from
-   custom external triggers only in that they are provided with Cylc.
+   custom external triggers only in that they are provided with Cylc, and
+   that the ``:interval`` suffix has no effect.
 
 
 Clock Triggering
@@ -135,9 +136,9 @@ Edit the ``[[scheduling]]`` section to read:
    initial cycle point = now
    final cycle point = +P1D # Run for one day
    [[xtriggers]]
-       quarter_past_trigger = wall_clock(offset=PT15M):PT30S
-       half_past_trigger = wall_clock(offset=PT30M):PT30S
-       quarter_to_trigger = wall_clock(offset=PT45M):PT30S
+       quarter_past_trigger = wall_clock(offset=PT15M)
+       half_past_trigger = wall_clock(offset=PT30M)
+       quarter_to_trigger = wall_clock(offset=PT45M)
    [[graph]]
        PT1H = """
            @wall_clock => bell
@@ -165,15 +166,6 @@ Leave your workflow running for a while to confirm it is working as expected
 before stopping it.
 
 
-.. note::
-
-   You may have noticed the ``:PT30S`` at the end of each clock trigger
-   definition. This how often the :ref:`Section External Triggers` is checked.
-   By default external triggers are checked every 10 seconds, but if there
-   are a lot of external triggers this can be hard work for the computer
-   running the workflow and it may not be necessary to check this often.
-
-
 Summary
 -------
 

src/tutorial/scheduling/further-scheduling.rst

@@ -75,7 +75,7 @@ Clock Triggers
    [scheduling]
        initial cycle point = 2000-01-01T00Z
        [[xtriggers]]
-           PT1H_trigger = wall_clock(offset=-PT1H):PT30S
+           PT1H_trigger = wall_clock(offset=-PT1H)
        [[graph]]
            # "daily" will run, at the earliest, one hour before midday.
            T12 = @PT1H_trigger => daily