Fix additional tutorials (#388)

* Updated clock-triggered-tasks tutorial
* fix cylc broadcast torial
* fixed up family triggers tutorial
* Inheritance tutorial
* updated queues tutorial
* updated retries
* updated message triggeres tutorial
* add cylc validate prior to all instances of cylc install
* fixed flow.cylc indentation
* Apply suggestions from code review
Co-authored-by: Oliver Sanders <[email protected]>
Co-authored-by: Ronnie Dutta <[email protected]>
* refactor refs to GUI/TUI
* Apply suggestions from code review
Co-authored-by: Ronnie Dutta <[email protected]>
*Ensure user has a UI running before playing a workflow which might
otherwise run too fast to see.
* Update src/tutorial/furthertopics/clock-triggered-tasks.rst
Co-authored-by: Ronnie Dutta <[email protected]>
Co-authored-by: Oliver Sanders <[email protected]>

Author: 3 people

src/7-to-8/summary.rst

@@ -330,7 +330,7 @@ Cylc Install
 
 .. seealso::
 
-   :ref:`Moving to Cylc Install<majorchangesinstall>`.
+   * :ref:`Moving to Cylc Install<majorchangesinstall>`.
 
 
 Cylc install cleanly separates workflow source directory from run directory,

src/tutorial/furthertopics/broadcast.rst

@@ -20,11 +20,11 @@ runs on.
 Standalone Example
 ------------------
 
-Create a new workflow in the ``cylc-run`` directory called
+Create a new workflow in the ``cylc-src`` directory called
 ``tutorial-broadcast``::
 
-   mkdir ~/cylc-run/tutorial-broadcast
-   cd ~/cylc-run/tutorial-broadcast
+   mkdir ~/cylc-src/tutorial-broadcast
+   cd ~/cylc-src/tutorial-broadcast
 
 Copy the following configuration into a :cylc:conf:`flow.cylc` file:
 
@@ -69,6 +69,8 @@ whilst the workflow is running. For instance we could change the value of the
 Run the workflow then try using the ``cylc broadcast`` command to change the
 message::
 
+   cylc validate .
+   cylc install
    cylc play tutorial-broadcast
    cylc broadcast tutorial-broadcast -n announce -s "[environment]WORD=it"
 
@@ -118,7 +120,8 @@ Add the following runtime configuration to the ``runtime`` section:
            [[[environment]]]
                WORDS = ni, it, ekke ekke ptang zoo boing
 
-Run the workflow and inspect the log. You should see the message change randomly
+Re-install and run the workflow, and inspect the log.
+You should see the message change randomly
 after every third entry (because the ``change_word`` task runs every 3 hours)
 e.g::
 

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

@@ -38,11 +38,11 @@ Example
 
 Our example workflow will simulate a clock chiming on the hour.
 
-Within your ``~/cylc-run`` directory create a new directory called
+Within your ``~/cylc-src`` directory create a new directory called
 ``clock-trigger``::
 
-   mkdir ~/cylc-run/clock-trigger
-   cd ~/cylc-run/clock-trigger
+   mkdir ~/cylc-src/clock-trigger
+   cd ~/cylc-src/clock-trigger
 
 Paste the following code into a ``flow.cylc`` file:
 
@@ -72,15 +72,14 @@ of times equal to the (cycle point) hour.
 
 Run your workflow using::
 
+   cylc validate .
+   cylc install
    cylc play clock-trigger
 
 Stop the workflow after a few cycles using ``cylc stop --now --now clock-trigger``.
 Notice how the tasks run as soon as possible rather than
 waiting for the actual time to be equal to the cycle point.
 
-.. TODO - check this tutorial still works now that cylc run/restart has been
-   replaced by cylc play
-
 
 Clock-Triggering Tasks
 ----------------------
@@ -98,7 +97,7 @@ your ``flow.cylc``:
 This tells the workflow to clock trigger the ``bell`` task with a cycle
 offset of ``0`` hours.
 
-Save your changes and run your workflow.
+Save your changes, install and run your workflow.
 
 Your workflow should now be running the ``bell`` task in real-time. Any cycle times
 that have already passed (such as the one defined by ``initial cycle time``)
@@ -133,6 +132,8 @@ Edit the ``[[scheduling]]`` section to read:
 
 .. code-block:: cylc
 
+   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
@@ -147,19 +148,21 @@ Edit the ``[[scheduling]]`` section to read:
 
 Note the different values used for the cycle offsets of the clock-trigger tasks.
 
-Save your changes and run your workflow using::
+Save your changes, install and run your workflow using::
 
-   cylc play clock-trigger now
+   cylc validate .
+   cylc install
+   cylc play clock-trigger
 
 .. note::
 
-   The ``now`` argument will run your workflow using the current time for the
-   initial cycle point.
+   Setting ``initial cycle point = now`` will run your workflow using the
+   current time at startup as the initial cycle point.
 
 Again, notice how the tasks trigger until the current time is reached.
 
 Leave your workflow running for a while to confirm it is working as expected
-and then shut it down using the :guilabel:`stop` button in the ``cylc gui``.
+before stopping it.
 
 
 .. note::

src/tutorial/furthertopics/family-triggers.rst

@@ -21,13 +21,20 @@ that the dependency refers to the ``succeed`` state e.g:
 
 .. code-block:: cylc-graph
 
-   bake_bread => sell_bread          # sell_bread is dependent on bake_bread succeeding.
-   bake_bread:succeed => sell_bread  # sell_bread is dependent on bake_bread succeeding.
-   sell_bread:fail => through_away   # through_away is dependent on sell_bread failing.
+   bake_bread => sell_bread           # sell_bread is dependent on bake_bread succeeding.
+   bake_bread:succeed => sell_bread?  # sell_bread is dependent on bake_bread succeeding.
+   sell_bread:fail? => throw_away     # throw_away is dependent on sell_bread failing.
 
 The left-hand side of a :term:`dependency` (e.g. ``sell_bread:fail``) is
 referred to as the :term:`trigger <task trigger>`.
 
+.. note::
+
+   ``sell_bread(:succeed)`` and ``sell_bread:fail`` are mutually exclusive
+   outcomes. As both appear in the graph above, it is
+   necessary to use the ``?`` syntax to mark them as
+   :ref:`optional outputs`.
+
 When we write a trigger involving a family, special qualifiers are required
 to specify whether the dependency is concerned with *all* or *any* of the tasks
 in that family reaching the desired :term:`state <task state>` e.g:
@@ -45,8 +52,8 @@ Example
 
 Create a new workflow called ``tutorial-family-triggers``::
 
-   mkdir ~/cylc-run/tutorial-family-triggers
-   cd ~/cylc-run/tutorial-family-triggers
+   mkdir ~/cylc-src/tutorial-family-triggers
+   cd ~/cylc-src/tutorial-family-triggers
 
 Paste the following configuration into the :cylc:conf:`flow.cylc` file:
 
@@ -81,8 +88,10 @@ You have now created a workflow that:
   or fails.
 * Has 7 tasks that inherit from the ``MINERS`` family.
 
-Run the workflow::
+Validate, install and run the workflow::
 
+   cylc validate .
+   cylc install
    cylc play tutorial-family-triggers
 
 You should see the ``visit_mine`` task run, then trigger the members of the
@@ -113,8 +122,8 @@ this:
 
    [[graph]]
        R1 = """
-           visit_mine => MINERS
-           MINERS:finish-all & MINERS:succeed-any => sell_diamonds
+           visit_mine => MINERS?
+           MINERS:finish-all & MINERS:succeed-any? => sell_diamonds
        """
 
 Then, add the following task to the ``[runtime]`` section:
@@ -131,6 +140,10 @@ Save your changes and run your workflow. You should see the new
 ``sell_diamonds`` task being run once all the miners have finished and at
 least one of them has succeeded. Stop your workflow as described above.
 
+.. seealso::
+
+   User guide on
+   :ref:`family triggers and optional outputs<optional outputs.family triggers>`.
 
 Family Triggering: Failure
 --------------------------
@@ -149,10 +162,9 @@ this:
 
    [[graph]]
        R1 = """
-           visit_mine => MINERS
-           MINERS:finish-all & MINERS:succeed-any => sell_diamonds
-           MINERS:finish-all & MINERS:fail-any => close_shafts
-           close_shafts => !MINERS
+           visit_mine => MINERS?
+           MINERS:finish-all & MINERS:succeed-any? => sell_diamonds
+           MINERS:finish-all & MINERS:fail-any? => close_shafts
        """
 
 Alter the ``[[sell_diamonds]]`` section to look like this:
@@ -163,7 +175,7 @@ Alter the ``[[sell_diamonds]]`` section to look like this:
        script = sleep 5
 
 These changes add a ``close_shafts`` task which is run once all the
-``MINERS`` tasks have finished and any of them have failed. 
+``MINERS`` tasks have finished and any of them have failed.
 
 Save your changes and run your workflow. You should see the new
 ``close_shafts`` run should any of the ``MINERS`` tasks be in the failed

src/tutorial/furthertopics/index.rst

@@ -1,3 +1,5 @@
+.. _tutorials.furthertopics:
+
 Further Topics
 ==============
 

src/tutorial/furthertopics/inheritance.rst

@@ -13,11 +13,11 @@ multiple inheritance.
 Inheritance Hierarchy
 ---------------------
 
-Within your ``~/cylc-run`` directory create a new directory called
+Within your ``~/cylc-src`` directory create a new directory called
 ``inheritance-tutorial``::
 
-   mkdir ~/cylc-run/inheritance-tutorial
-   cd ~/cylc-run/inheritance-tutorial
+   mkdir ~/cylc-src/inheritance-tutorial
+   cd ~/cylc-src/inheritance-tutorial
 
 And paste the following code into a ``flow.cylc`` file. This
 defines two tasks each representing different aircraft, the Airbus A380 jumbo
@@ -74,7 +74,7 @@ jet and the Robson R44 helicopter:
    The ``[meta]`` section is a freeform section where we can define metadata
    to be associated with a task, family or the workflow itself.
 
-   This metadata should not be mistaken with Rose :ref:`conf-meta`.
+   This metadata should not be mistaken for Rose :ref:`conf-meta`.
 
 .. admonition:: Reminder
    :class: hint
@@ -183,7 +183,7 @@ Add the following task to your :cylc:conf:`flow.cylc` file.
            [[[meta]]]
                title = V-22 Osprey Military Aircraft.
 
-Refresh your ``cylc graph`` window or re-run the ``cylc graph`` command.
+Re-run the ``cylc graph`` command.
 
 The inheritance hierarchy should now look like this: