Update tutorials (#2776)

* Tutorials: fix incorrect link & clarify
* Replace references to `rose date` with `isodatetime`
* Docs: automatically include hyperlinks for use in every page
* GH Actions: disable docs slides build test as it doesn't work currently
* Tutorials: fix mistake

.github/workflows/test.yml

@@ -263,9 +263,9 @@ jobs:
         run: |
           make -C sphinx/ html SPHINXOPTS='-Wn'
 
-      - name: build (slides)
-        run: |
-          make -C sphinx/ slides SPHINXOPTS='-Wn'
+      # - name: build (slides)
+      #   run: |
+      #     make -C sphinx/ slides SPHINXOPTS='-Wn'
 
       - name: build (linkcheck)
         run: |

pytest.ini

@@ -10,6 +10,7 @@ addopts =
     # these tests do IO, don't run them under sphinx-build rather than pytest:
     --ignore=metomi/rose/config.py
     --ignore=metomi/rose/macro.py
+    --ignore=sphinx/conf.py
 testpaths =
     metomi/
     sphinx/

sphinx/api/built-in/rose_prune.rst

@@ -1,6 +1,3 @@
-.. include:: ../../hyperlinks.rst
-   :start-line: 1
-
 .. _builtin.rose_prune:
 
 ``rose_prune``

sphinx/api/configuration/metadata.rst

@@ -1,6 +1,3 @@
-.. include:: ../../hyperlinks.rst
-   :start-line: 1
-
 .. _floating point: https://docs.python.org/3/library/stdtypes.html#typesnumeric
 .. _cast: https://docs.python.org/3/library/ast.html#ast.literal_eval
 .. _Python in operator: https://docs.python.org/3/reference/expressions.html#membership-test-operations
@@ -687,15 +684,15 @@ The metadata options for a configuration fall into four categories:
 
          .. _trigger-file-creation:
 
-         It is possible to use metadata triggers to trigger file creation, 
+         It is possible to use metadata triggers to trigger file creation,
          switching on/off as required.
 
-         For example, with the following :rose:file:`rose-app.conf` and 
+         For example, with the following :rose:file:`rose-app.conf` and
          :rose:file:`rose-meta.conf` files, file creation is triggered when
-         setting ``trigger=file:foo`` to ``.true.``. 
+         setting ``trigger=file:foo`` to ``.true.``.
 
 
-         :rose:file:`rose-app.conf` file: 
+         :rose:file:`rose-app.conf` file:
 
          .. code-block:: rose
 
@@ -708,7 +705,7 @@ The metadata options for a configuration fall into four categories:
             [namelist:foo]
             switch=.false.
 
-         :rose:file:`rose-meta.conf` file:  
+         :rose:file:`rose-meta.conf` file:
 
          .. code-block:: rose
 

sphinx/api/configuration/rose-configuration-format.rst

@@ -1,6 +1,3 @@
-.. include:: ../../hyperlinks.rst
-   :start-line: 1
-
 .. _Rose Configuration Format:
 
 Rose Configuration Format

sphinx/api/configuration/suite.rst

@@ -1,6 +1,3 @@
-.. include:: ../../hyperlinks.rst
-   :start-line: 1
-
 .. _Rose Suites:
 
 Suite Configuration

sphinx/conf.py

@@ -83,6 +83,8 @@
     'python': ('https://docs.python.org/', None),
 }
 
+rst_epilog = open('hyperlinks.rst', 'r').read()
+
 # Slide (hieroglyph) settings.
 slide_theme = 'single-level'
 slide_link_to_html = True

sphinx/getting-started.rst

@@ -1,7 +1,3 @@
-.. include:: hyperlinks.rst
-   :start-line: 1
-
-
 Getting Started
 ===============
 
@@ -29,7 +25,7 @@ configuration file ``~/.metomi/rose.conf``:
 
 ``[external]geditor``
    The external text editor used by GUIs
-``[external]editor`` 
+``[external]editor``
    The external text editor used by CLI commands
 
 For emacs and most text editors, you can do something like:

sphinx/glossary.rst

@@ -1,6 +1,3 @@
-.. include:: hyperlinks.rst
-   :start-line: 1
-
 Glossary
 ========
 

sphinx/hyperlinks.rst

@@ -3,17 +3,14 @@
 .. This document contains hyperlink references to be used throughout the
    documentation.
 
-   To use hyperlinks defined in this file add the following code at the top of
-   the file::
-
-       .. include:: path/to/thisfile.rst
-          :start-line: 1
+   They are automatically included for use in every page (via conf.py)
 
 .. _Cylc: https://cylc.github.io/
 .. _Cylc Flow: https://github.com/cylc/cylc-flow
 .. _Cylc Rose: https://github.com/cylc/cylc-rose
 .. _Cylc User Guide: https://cylc.github.io/cylc-doc/stable/html/user-guide/index.html
 .. _Cylc Workflow Design Guide: https://cylc.github.io/cylc-doc/stable/html/workflow-design-guide/index.html
+.. _isodatetime: https://github.com/metomi/isodatetime
 
 .. _EmPy: https://pypi.org/project/empy/
 .. _extglob pattern matching: https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html#Pattern-Matching

sphinx/index.rst

@@ -1,6 +1,3 @@
-.. include:: hyperlinks.rst
-   :start-line: 1
-
 .. ifnotslides::
 
    .. raw:: html

sphinx/installation.rst

@@ -1,7 +1,3 @@
-.. include:: hyperlinks.rst
-   :start-line: 1
-
-
 Installation
 ============
 
@@ -121,27 +117,27 @@ Check the following:
 1. You can access the Rosie Subversion repository without being prompted
    for a username and a password. This may require configuring Subversion
    to cache your authentication information with a keyring.
-   
+
    *(See Subversion Book > Advanced Topics > Network Model > Client
    Credentials for a discussion on how to do this.)*
 
 2. The Rosie web service is up and running and you can access the Rosie
    web service from your computer. E.g. if the Rosie web service is
    hosted at ``https://somehost.on.the.internet/rosie/x``, you can check
    that you have access by typing the following on the command line::
-   
+
       curl -I https://somehost.on.the.internet/rosie/x
-      
+
    It should return a HTTP code 200. If you are prompted for a username
    and a password, you may need to have access to a keyring to cache
    the authentication information.
 
 3. You can access the Rosie web service using the Rosie client. E.g.
    using the above configuration for the prefix ``x``, type the
    following on the command line::
-   
+
       rosie hello --prefix=x
-      
+
    It should return a greeting, e.g. ``Hello user``.
 
 

sphinx/tutorial/rose/applications.rst

@@ -1,6 +1,3 @@
-.. include:: ../../hyperlinks.rst
-   :start-line: 1
-
 
 .. _tutorial-rose-applications:
 
@@ -136,7 +133,8 @@ An application can be run using the :ref:`command-rose-app-run` command:
 .. ifslides::
 
    .. rubric:: In this practical we will convert the ``forecast`` task from the
-      :ref:`weather-forecasting workflow <tutorial-datetime-cycling-practical>`
+      weather-forecasting workflow in the
+      :ref:`Cylc tutorials <tutorial-cylc-runtime-forecasting-workflow>`
       into a Rose application.
 
    Next section: :ref:`tutorial-rose-metadata`
@@ -147,8 +145,11 @@ An application can be run using the :ref:`command-rose-app-run` command:
 .. practical::
 
    .. rubric:: In this practical we will convert the ``forecast`` task from the
-      :ref:`weather-forecasting workflow <tutorial-datetime-cycling-practical>`
-      into a standalone Rose application.
+      weather-forecasting workflow in the
+      :ref:`Cylc tutorials <tutorial-cylc-runtime-forecasting-workflow>`
+      into a standalone Rose application. By the end you will be able to run
+      the application standalone (running it as a task in the workflow will
+      come later).
 
    Create a directory on your filesystem called ``rose-tutorial``::
 
@@ -166,8 +167,7 @@ An application can be run using the :ref:`command-rose-app-run` command:
    #. **Provide the required resources in the** ``application-tutorial``
       **application.**
 
-      The application gets three resources from different places in the
-      :ref:`weather-forecasting workflow <tutorial-datetime-cycling-practical>`:
+      The application gets three resources from different places:
 
       * The ``bin/forecast`` script.
       * The ``lib/python/util.py`` Python library.
@@ -227,17 +227,15 @@ An application can be run using the :ref:`command-rose-app-run` command:
    #. **Move environment variables defined in the** ``flow.cylc`` **file.**
 
       In the ``[runtime][forecast][environment]`` section of the ``flow.cylc``
-      file in the
-      :ref:`weather-forecasting workflow <tutorial-datetime-cycling-practical>`
-      we set a few environment variables:
+      file in the weather-forecasting workflow we set a few environment variables:
 
       * ``WIND_FILE_TEMPLATE``
       * ``WIND_CYCLES``
       * ``RAINFALL_FILE``
       * ``MAP_FILE``
       * ``MAP_TEMPLATE``
 
-      We will now move these into the application. This way, all of the
+      We will now add these into the application. This way, all of the
       configuration specific to the application live within it.
 
       Add the following lines to the :rose:conf:`rose-app.conf[env]` section:
@@ -263,8 +261,8 @@ An application can be run using the :ref:`command-rose-app-run` command:
       variables are pointing at files in the ``test-data`` directory.
 
       To make this application work outside of the weather forecasting workflow
-      we will also need to
-      provide the ``DOMAIN`` and ``RESOLUTION`` environment variables defined
+      we will also need to provide the ``DOMAIN`` and ``RESOLUTION``
+      environment variables that were defined
       in the ``[runtime][root][environment]`` section of the ``flow.cylc``
       file as well as the ``CYLC_TASK_CYCLE_POINT`` environment variable
       provided by Cylc when it runs a task.

sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst

@@ -4,73 +4,69 @@ Date and Time Manipulation
 ==========================
 
 :term:`Datetime cycling <datetime cycling>` suites inevitably involve
-performing some form of datetime arithmetic. In the
-:ref:`weather forecasting suite <tutorial-datetime-cycling-practical>` we wrote
-in the Cylc tutorial this arithmetic was done using the ``cylc cyclepoint``
-command. For example we calculated the cycle point three hours before the
+performing some form of datetime arithmetic. For example, in a Cylc task we
+can calculate the cycle point three hours before the
 present cycle using::
 
    cylc cyclepoint --offset-hours=-3
 
-Rose provides the :ref:`command-rose-date` command which provides functionality
-beyond ``cylc cyclepoint`` as well as the :envvar:`ROSE_DATAC` environment
+The `isodatetime`_ command provides functionality
+beyond ``cylc cyclepoint``. Rose also provides the :envvar:`ROSE_DATAC` environment
 variable which provides an easy way to get the path of the ``share/cycle``
 directory.
 
 
-The ``rose date`` Command
--------------------------
+The ``isodatetime`` Command
+---------------------------
 
-The :ref:`command-rose-date` command provides functionality for:
+The ``isodatetime`` command provides functionality for:
 
 * Parsing and formatting datetimes e.g:
 
   .. code-block:: console
 
-     $ rose date '12-31-2000' --parse-format='%m-%d-%Y'
+     $ isodatetime 12-31-2000 --parse-format='%m-%d-%Y'
      12-31-2000
-     $ rose date '12-31-2000' --parse-format='%m-%d-%Y' --format='DD-MM-CCYY'
+     $ isodatetime 12-31-2000 --parse-format='%m-%d-%Y' --format='DD-MM-CCYY'
      31-12-2000
 
 * Adding offsets to datetimes e.g:
 
   .. code-block:: console
 
-     $ rose date '2000-01-01T0000Z' --offset '+P1M'
-     2000-02-01T0000Z
+     $ isodatetime 2000-01-01T00:00Z --offset '+P1M'
+     2000-02-01T00:00Z
 
 * Calculating the duration between two datetimes e.g:
 
   .. code-block:: console
 
-     $ rose date '2000' '2001'  # Note - 2000 was a leap year!
+     $ isodatetime 2000 2001  # Note - 2000 was a leap year!
      P366D
 
-See the :ref:`command-rose-date` command reference for more information.
+See the ``isodatetime --help`` command reference for more information.
 
 
-Using ``rose date`` In A Suite
-------------------------------
+Using ``isodatetime`` In A Suite
+--------------------------------
 
-In datetime cycling suites :ref:`command-rose-date` can work with the
+In datetime cycling suites, ``isodatetime`` can work with the
 cyclepoint using the ``CYLC_TASK_CYCLE_POINT`` environment variable:
 
 .. code-block:: cylc
 
    [runtime]
        [[hello_america]]
-           script = rose date $CYLC_TASK_CYCLE_POINT --format='MM-DD-CCYY'
+           script = isodatetime $CYLC_TASK_CYCLE_POINT --format='MM-DD-CCYY'
 
-Alternatively, if you are providing the standard Rose task environment using
-:ref:`command-rose-task-env` then :ref:`command-rose-date` can use the ``-c``
-option to pick up the cycle point:
+Alternatively, Cylc automatically sets the ``ISODATETIMEREF`` environment variable
+which allows you to use the special ``ref`` argument:
 
 .. code-block:: cylc
 
    [runtime]
        [[hello_america]]
-           env-script = eval $(rose task-env)
-           script = rose date -c --format='MM-DD-CCYY'
+           script = isodatetime ref --format='MM-DD-CCYY'
 
 
 The ``ROSE_DATAC`` Environment Variable
@@ -118,4 +114,4 @@ provide an offset to :ref:`command-rose-task-env` e.g::
 
 The path is then made available as the ``ROSE_DATACPT1H`` environment variable.
 
-.. TODO - Write a short practical using ROSE_DATAC and rose-date.
+.. TODO - Write a short practical using ROSE_DATAC and isodatetime.

sphinx/tutorial/rose/furthertopics/optional-configurations.rst

@@ -131,7 +131,7 @@ You should see the following:
 
 .. code-block:: none
 
-   I'd like to order a chocolate icecream in a tub with nuts.
+   I'd like to order a chocolate ice cream in a tub with nuts.
 
 The ``chocolate`` configuration has overwritten the ``FLAVOUR`` environment
 variable from the ``fudge sundae`` configuration. This is because optional
@@ -142,7 +142,7 @@ To see how the optional configurations would be applied use the
 :ref:`command-rose-config` command providing the configuration files in the
 order they would be loaded::
 
-   rose config --file rose-app.conf --file opt/rose-app-fudge-sundae --file chocolate
+   rose config --file rose-app.conf --file opt/rose-app-fudge-sundae.conf --file opt/rose-app-chocolate.conf
 
 You should see:
 

sphinx/tutorial/rose/rosie.rst

@@ -1,6 +1,3 @@
-.. include:: ../../hyperlinks.rst
-   :start-line: 1
-
 .. _tutorial-rosie:
 
 Rosie
@@ -146,7 +143,7 @@ Rosie provides commands for managing suites, including:
 .. ifslides::
 
    .. rubric:: In this practical we will add the
-      :ref:`weather-forecasting suite <tutorial-datetime-cycling-practical>`
+      weather-forecasting suite
       from the :ref:`previous practical <suites-practical>` to a rosie
       repository, make some changes, and commit them to the repository.
 
@@ -156,7 +153,7 @@ Rosie provides commands for managing suites, including:
 .. practical::
 
    .. rubric:: In this practical we will add the
-      :ref:`weather-forecasting suite <tutorial-datetime-cycling-practical>`
+      weather-forecasting suite
       from the :ref:`previous practical <suites-practical>` to a rosie
       repository, make some changes, and commit them to the repository.