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

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

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.

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

oliver-sanders · 2026-04-27T10:55:26Z

+   jinja2
+   families
+   parameters


This changes the order in which the tutorials are attempted.

Does this work?

I believe this is just correcting the order in this sub-list so it matches the order elsewhere. This is section 3 in the image:

Try attempting the Jinja2 tutorial without first attempting the Families tutorial. There's a dependency between them.

The step numbers in the practicals outline the intended order:

Families 1 & 2.

Jinja2 3.

Parameters 4.

The previous order was correct, i.e, it's the bit above which needs to change for consistency.

Ah ok, I'll have another look.
If that is the case, and I think you are right, we are going to need to alter the toctree in a few places as currently, both the contents page and the menu go JinJa2 > Fam > Params. Currently, going page by page from the start will be JinJa2 > Fam.
Let me confirm the order 100% and I'll make that change.

Reducing duplicated explanations. Co-authored-by: Oliver Sanders <[email protected]>

Previous description sounded like the sleep 5 was important or changed the behaviour rather than emulating real behaviour.

samuel-denton · 2026-04-27T14:52:12Z

Checks failing due to rate limit during linkcheck.

oliver-sanders · 2026-04-28T10:45:01Z

Checks failing due to rate limit during linkcheck.

The linkcheck test did fail, but not due to rate limiting. The message was:

Failed to establish a new connection: [Errno 101] Network is unreachable"))

I.e, the site was down.

samuel-denton · 2026-04-28T10:55:39Z

Checks failing due to rate limit during linkcheck.

The linkcheck test did fail, but not due to rate limiting. The message was:
Failed to establish a new connection: [Errno 101] Network is unreachable"))
I.e, the site was down.

Yep you're correct, the error starts: "Max retries exceeded with url" which I misinterpreted as a rate limit

Do we need to investigate / correct this URL?

samuel-denton · 2026-04-28T14:58:54Z

Getting there:
https://wwwspice/~samuel.denton/cylc-doc/batch2_thoughts_on_docs/html/tutorial/runtime/configuration-consolidation/index.html

Still need to run through the tutorials again to check this all makes sense. I've definitely missed some bits.

samuel-denton · 2026-04-28T15:07:56Z

 .. ifslides::

   .. rubric:: This practical continues on from the
-      :ref:`Families practical <cylc-tutorial-families-practical>`.
+      :ref:`Jinja2 practical <cylc-tutorial-jinja2-practical>`.

   Next section: :ref:`Which approach to use
   <cylc-tutorial-consolidation-conclusion>`


It's currently inconsistent which pages make use of the ifslides / ifnotslides blocks. Are these still used for anything? I understood they were previously used for allowing the docs to generate in other formats but not sure if anything still uses them @oliver-sanders ? I can make an effort to clean them up if not, or add any missing if they are need. The JinJa2 page for example is missing some compared to the parametrization or families pages.

samuel-denton · 2026-04-30T16:20:30Z

I have run through the tutorials multiple times and I think I am now happy with the order and the accompanying text.
Only thing I have a question about is the slightly inconsistent use of ifslides / ifnotslides but not sure thats relavent to this PR anyway.
Please review alongside cylc/cylc-flow#7289 and close #924 if both are ok.

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 Apr 27, 2026

View reviewed changes

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

Apply suggestion from @oliver-sanders

a8572f0

Reducing duplicated explanations. Co-authored-by: Oliver Sanders <[email protected]>

samuel-denton commented Apr 27, 2026

View reviewed changes

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

Apply suggestion from @samuel-denton

c9d07d0

Previous description sounded like the sleep 5 was important or changed the behaviour rather than emulating real behaviour.

samuel-denton requested a review from oliver-sanders April 27, 2026 14:53

samuel-denton mentioned this pull request Apr 28, 2026

The order of tutorials has gotten a bit confused. #924

Open

samuel-denton marked this pull request as draft April 28, 2026 14:11

samuel-denton mentioned this pull request Apr 28, 2026

Fixing tutorials due to an order change which didn't quite work. cylc/cylc-flow#7289

Open

8 tasks

Started re-organizing tutorials so they make sense in order.

3a5972d

samuel-denton commented Apr 28, 2026

View reviewed changes

small layout improvements to tutorial diffs

e7ad72c

samuel-denton marked this pull request as ready for review April 30, 2026 16:20

samuel-denton requested a review from ChrisPaulBennett April 30, 2026 16:23

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!

ChrisPaulBennett left a comment

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!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

oliver-sanders commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

samuel-denton commented Apr 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

samuel-denton commented Feb 4, 2026 •

edited

Loading

samuel-denton Mar 17, 2026 •

edited

Loading

samuel-denton Mar 18, 2026 •

edited

Loading

samuel-denton commented Apr 27, 2026 •

edited

Loading

oliver-sanders commented Apr 28, 2026 •

edited

Loading

samuel-denton commented Apr 28, 2026 •

edited

Loading

samuel-denton commented Apr 30, 2026 •

edited

Loading