Various small proposed improvements by samuel-denton · Pull Request #909 · cylc/cylc-doc

samuel-denton · 2026-02-04T13:24:49Z

https://wwwspice/~samuel.denton/cylc-doc/batch2_thoughts_on_docs/html/index.html

Requirements check-list

I have read CONTRIBUTING.md and added my name as a Code Contributor.
Fixed a mistake on the interventions page causing tabs not to sync properly.
Adding tabs to the intro page to show different UI types. I find the current image a bit intimidating.
Added a note to Basic Cycling - Repeating Workflows to describe the reoccurrence in the example.

samuel-denton · 2026-02-04T13:27:30Z


   .. tab-item:: CLI
-      :sync: gui
+      :sync: cli


Small mistake here caused tabs to sync incorrectly.

samuel-denton · 2026-02-04T16:54:30Z

     from 1.
   * ``P1`` is the :term:`recurrence`; a ``P1`` :term:`graph string`
-     repeats at every integer :term:`cycle point`.
+     tells Cylc to repeat at every integer :term:`cycle point`.


Minor change to keep consistency with other bullets.

samuel-denton · 2026-03-17T11:26:15Z

-.. tip::
-
-   We recommend using Mamba to install Cylc.
-   Mamba (or Micromamba) can be used as
-   `a faster, drop-in replacement for the conda command
-   <https://mamba.readthedocs.io/en/latest/index.html>`_.
-   If using Conda, make sure to use the libmamba-solver by updating to
-   Conda 23.10 or using the `conda-libmamba-solver plugin for conda
-   <https://conda.github.io/conda-libmamba-solver/getting-started/>`_.
-   The classic conda environment solver may be too slow for a complex package
-   like Cylc.


#916 (comment)

This tip is no longer relevant thanks to conda adopting the Libmamba dependency resolver

samuel-denton · 2026-03-18T10:21:28Z

               mail events = failed
       [[bell]]
-           script = printf 'bong%.02d\n' $(seq 1 $(cylc cyclepoint --print-hour))
+           script = printf 'bong%.02d\n' $(seq 1 $(cylc cyclepoint --print-hour)); sleep 5


Added sleep 5 to tutorial to allow users time to see the workflow running. A previous update to cylc sped up the running of this workflow significantly.

samuel-denton · 2026-03-18T10:41:20Z

-   * :term:`Families <family>` work best consolidating runtime configuration by
-     collecting tasks into broad groups, e.g. groups of tasks which run on a
-     particular machine or groups of tasks belonging to a particular system.
   * `Jinja2`_ is good at configuring settings which apply to the entire workflow
     rather than just a single task, as we can define variables then use them
     throughout the workflow.
+   * :term:`Families <family>` work best consolidating runtime configuration by
+     collecting tasks into broad groups, e.g. groups of tasks which run on a
+     particular machine or groups of tasks belonging to a particular system.
   * :term:`Parameterization <parameterization>` works best for describing tasks
     which are very similar but which have subtly different configurations
     (e.g. different arguments or environment variables).


Reorder to match toc tree

GH should be showing this as outdated as the change is reverted in a following commit.

samuel-denton · 2026-03-18T11:19:31Z

-.. image:: /tutorial/img/cylc-tools.png
-   :alt: A screenshot of several Cylc tools.
+**Placeholder Images Currently Used**
+
+.. tab-set::
+
+   .. tab-item:: GUI
+
+      .. image:: ../../src/img/cylc-ui-dash.png
+         :alt: A screenshot of the Cylc GUI dashboard.
+         :width: 75%
+
+   .. tab-item:: Tui
+
+      .. image:: ../../src/img/tui-1.png
+         :alt: A screenshot of the Cylc TUI.
+         :width: 75%
+
+   .. tab-item:: CLI
+
+      .. image:: ../../src/img/cylc-cli.png
+         :alt: A screenshot of the Cylc CLI.
+         :width: 75%


I think these tabs are a little clearer and less intimidating than the combined image used before.

cylc-tools.png can be deleted as it is no longer used.

Also, can you remove the width directive as it makes the images smaller and harder to see properly?

The text above mentions cylc scan but it is not present in the CLI screenshot. Also the CLI screenshot text is rather small even with the width directive removed.

Sorry that was a bunch of alsos 😄

samuel-denton · 2026-03-18T12:17:08Z

Lots of small wording changes to clarify what is and is not installed via pip vs conda.

…xed a mistake on the interventions page causing tabs to not sync properly.

…ormatting.

…ncy resolver

Added sleep 5 to a tutorial and added a description of why wallclock triggers are required to run tasks in real time.

…ion so the 2 places they are listed match.

…nd CLI.

ChrisPaulBennett

LGTM

Old note removed. Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>

samuel-denton · 2026-05-18T16:08:04Z

+              # Generate a forecast for Exeter 300 minutes into the future.
+              script = post-process exeter 300


This is to match the change in the Jinja2 tutorial.

oliver-sanders · 2026-05-20T13:37:27Z

There's a bit of a problem in tutorial/runtime/configuration-consolidation/families.

It starts like so:

Families are groups of tasks which share a common configuration. In the present example the common configuration is:
script = get-observations
[[[environment]]]
    GET_NEARBY = true

However, there is no GET_NEARBY variable in the snippet on the previous change, or the previous tutorial.

The variables it then gets us to consolidate are RESOLUTION and DOMAIN:

+ [runtime]
+    [[root]]
+        [[[environment]]]
+            # The dimensions of each grid cell in degrees.
+            RESOLUTION = 0.2
+            # The area to generate forecasts for (lng1, lat1, lng2, lat2).
+            DOMAIN = -12,46,12,61  # Do not change!

samuel-denton · 2026-05-21T15:27:59Z

However, there is no GET_NEARBY variable in the snippet on the previous change, or the previous tutorial.

I had spotted that, but I though the explainer text was somewhat separate from the practicals. The Jinja2 one for example talks about lots of things that are not touched in the practical. However I can see that it could be confusing if someone was going page by page reading the whole thing as it uses the same examples as the practical. I can look at re-wording that bit to describe one of the variables actually consolidated.

MetRonnie · 2026-05-21T16:12:20Z

+      so you should not see any difference after making these changes, other than
+      the MAP_FILE filename now including the resolution.


I think the filename change is no longer present in the PR?

Yep... I've changed this text so many times now I'm loosing track!

MetRonnie · 2026-05-21T16:49:33Z

-.. image:: /tutorial/img/cylc-tools.png
-   :alt: A screenshot of several Cylc tools.
+**Placeholder Images Currently Used**
+
+.. tab-set::
+
+   .. tab-item:: GUI
+
+      .. image:: ../../src/img/cylc-ui-dash.png
+         :alt: A screenshot of the Cylc GUI dashboard.
+         :width: 75%
+
+   .. tab-item:: Tui
+
+      .. image:: ../../src/img/tui-1.png
+         :alt: A screenshot of the Cylc TUI.
+         :width: 75%
+
+   .. tab-item:: CLI
+
+      .. image:: ../../src/img/cylc-cli.png
+         :alt: A screenshot of the Cylc CLI.
+         :width: 75%


cylc-tools.png can be deleted as it is no longer used.

Also, can you remove the width directive as it makes the images smaller and harder to see properly?

The text above mentions cylc scan but it is not present in the CLI screenshot. Also the CLI screenshot text is rather small even with the width directive removed.

Sorry that was a bunch of alsos 😄

Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>

Reworded the families page to closer match the examples being worked on.

samuel-denton · 2026-05-22T14:43:19Z

@oliver-sanders @MetRonnie
I believe all comments have been addressed so should be ready for another look.

Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>

MetRonnie

Thanks, this looks better now 👍 I don't have much time to go through the tutorials to check the code diffs etc are completely consistent with what you get, if someone could do so that would be great

samuel-denton commented Feb 4, 2026

View reviewed changes

Comment thread src/tutorial/scheduling/integer-cycling.rst Outdated

samuel-denton commented Feb 4, 2026

View reviewed changes

samuel-denton mentioned this pull request Mar 16, 2026

Simplify or explain some technical explanations #916

Closed

samuel-denton commented Mar 17, 2026

View reviewed changes

samuel-denton commented Mar 18, 2026

View reviewed changes

Comment thread src/tutorial/furthertopics/clock-triggered-tasks.rst Outdated

samuel-denton commented Mar 18, 2026

View reviewed changes

samuel-denton marked this pull request as ready for review March 18, 2026 13:43

samuel-denton requested a review from wxtim March 18, 2026 13:43

samuel-denton added this to the 8.6.x milestone Mar 18, 2026

samuel-denton added 9 commits March 18, 2026 14:45

Adding tabs to the introduction page showing each UI type. Spotted/fi…

aa2399d

…xed a mistake on the interventions page causing tabs to not sync properly.

Added tabs to the into and found some placeholder images to work on f…

465f46e

…ormatting.

Added a note explaining why R1 was swapped for P1 here.

13b6832

This tip no longer applies due to conda adopting the Libmamba depende…

4016765

…ncy resolver

Slight wording changes on the install instructions.

f41651c

Added sleep 5 to a tutorial and added a description of why wallclock triggers are required to run tasks in real time.

Fixed the order of 'The Three Approaches' in Consolidating Configurat…

af9a92c

…ion so the 2 places they are listed match.

Further reorder of approaches on consolidation to match toc.

7c2e36f

Added proper images for the introduction page tabs showing GUI, TUI a…

fb49049

…nd CLI.

Trying to clarify what packages need installing depending on method.

609cff9

samuel-denton force-pushed the batch2_thoughts_on_docs branch from b90fb1d to 609cff9 Compare March 18, 2026 14:55

samuel-denton changed the base branch from master to 8.6.x March 18, 2026 14:56

oliver-sanders requested review from ChrisPaulBennett and oliver-sanders and removed request for wxtim April 9, 2026 14:12

oliver-sanders assigned samuel-denton Apr 9, 2026

ChrisPaulBennett approved these changes Apr 27, 2026

View reviewed changes

cylc deleted a comment from samuel-denton Apr 27, 2026

oliver-sanders reviewed May 11, 2026

View reviewed changes

Comment thread src/tutorial/introduction.rst Outdated

Update src/tutorial/introduction.rst

d0af77a

Old note removed. Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>

samuel-denton marked this pull request as draft May 13, 2026 09:43

Re-worked the consolidation tutorials.

9b6a004

samuel-denton commented May 18, 2026

View reviewed changes

samuel-denton marked this pull request as ready for review May 18, 2026 16:32

samuel-denton requested review from ChrisPaulBennett and oliver-sanders May 18, 2026 16:32

oliver-sanders requested review from MetRonnie and removed request for ChrisPaulBennett May 20, 2026 13:30

MetRonnie reviewed May 21, 2026

View reviewed changes

samuel-denton and others added 6 commits May 22, 2026 12:20

Removed extra quote

7f25cfb

Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>

Reverted help text.

ec2f4df

Delete cylc-tools.png

fd8f02b

Increased image width in introduction.

24fd350

Update introduction.rst

9cd0717

new cylc-cli image.

2b6a4e9

Reworded the families page to closer match the examples being worked on.

samuel-denton requested a review from MetRonnie May 22, 2026 14:42

oliver-sanders reviewed May 26, 2026

View reviewed changes

Comment thread src/tutorial/runtime/configuration-consolidation/jinja2.rst Outdated

Comment thread src/tutorial/runtime/configuration-consolidation/parameters.rst Outdated

Comment thread src/tutorial/runtime/configuration-consolidation/families.rst Outdated

MetRonnie reviewed May 26, 2026

View reviewed changes

Comment thread src/tutorial/scheduling/integer-cycling.rst Outdated

samuel-denton and others added 5 commits May 27, 2026 10:37

Added comment to example

33eea11

Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>

Changed order of some diff text

9c2d534

Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>

Removed redundant example

e91c81b

Improved wording on recurrence terms

be7c9ad

Removed Jinja2 from comments in diff text

9a71138

MetRonnie self-requested a review May 27, 2026 10:37

MetRonnie approved these changes May 28, 2026

View reviewed changes

		# Generate a forecast for Exeter 300 minutes into the future.
		script = post-process exeter 300

		so you should not see any difference after making these changes, other than
		the MAP_FILE filename now including the resolution.

Conversation

samuel-denton commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samuel-denton Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samuel-denton Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChrisPaulBennett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliver-sanders commented May 20, 2026

Uh oh!

samuel-denton commented May 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samuel-denton commented May 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MetRonnie left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samuel-denton commented Feb 4, 2026 •

edited

Loading

samuel-denton Mar 17, 2026 •

edited

Loading

samuel-denton Mar 18, 2026 •

edited

Loading