diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 9f259d0651..0bdc2c35c3 100644 --- a/.github/workflows/test.yml +++ b/.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: | diff --git a/pytest.ini b/pytest.ini index df779adf1e..848b52b40e 100644 --- a/pytest.ini +++ b/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/ diff --git a/sphinx/api/built-in/rose_prune.rst b/sphinx/api/built-in/rose_prune.rst index ca3e1e8ea8..7638c4ed99 100644 --- a/sphinx/api/built-in/rose_prune.rst +++ b/sphinx/api/built-in/rose_prune.rst @@ -1,6 +1,3 @@ -.. include:: ../../hyperlinks.rst - :start-line: 1 - .. _builtin.rose_prune: ``rose_prune`` diff --git a/sphinx/api/configuration/metadata.rst b/sphinx/api/configuration/metadata.rst index 07f3792ed1..ce587956d2 100644 --- a/sphinx/api/configuration/metadata.rst +++ b/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 diff --git a/sphinx/api/configuration/rose-configuration-format.rst b/sphinx/api/configuration/rose-configuration-format.rst index 729bd4e204..c60daf0f09 100644 --- a/sphinx/api/configuration/rose-configuration-format.rst +++ b/sphinx/api/configuration/rose-configuration-format.rst @@ -1,6 +1,3 @@ -.. include:: ../../hyperlinks.rst - :start-line: 1 - .. _Rose Configuration Format: Rose Configuration Format diff --git a/sphinx/api/configuration/suite.rst b/sphinx/api/configuration/suite.rst index face5a4205..29cf048a02 100644 --- a/sphinx/api/configuration/suite.rst +++ b/sphinx/api/configuration/suite.rst @@ -1,6 +1,3 @@ -.. include:: ../../hyperlinks.rst - :start-line: 1 - .. _Rose Suites: Suite Configuration diff --git a/sphinx/conf.py b/sphinx/conf.py index f782405a24..15894a1c44 100644 --- a/sphinx/conf.py +++ b/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 diff --git a/sphinx/getting-started.rst b/sphinx/getting-started.rst index 0d6f78b87f..969e6fee37 100644 --- a/sphinx/getting-started.rst +++ b/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: diff --git a/sphinx/glossary.rst b/sphinx/glossary.rst index 0c993251fd..b5f35cc507 100644 --- a/sphinx/glossary.rst +++ b/sphinx/glossary.rst @@ -1,6 +1,3 @@ -.. include:: hyperlinks.rst - :start-line: 1 - Glossary ======== diff --git a/sphinx/hyperlinks.rst b/sphinx/hyperlinks.rst index f7723a4e4c..ebb1cc1fd2 100644 --- a/sphinx/hyperlinks.rst +++ b/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 diff --git a/sphinx/index.rst b/sphinx/index.rst index 463e13f78e..89f89fc386 100644 --- a/sphinx/index.rst +++ b/sphinx/index.rst @@ -1,6 +1,3 @@ -.. include:: hyperlinks.rst - :start-line: 1 - .. ifnotslides:: .. raw:: html diff --git a/sphinx/installation.rst b/sphinx/installation.rst index 3d380ba311..a787abd492 100644 --- a/sphinx/installation.rst +++ b/sphinx/installation.rst @@ -1,7 +1,3 @@ -.. include:: hyperlinks.rst - :start-line: 1 - - Installation ============ @@ -121,7 +117,7 @@ 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.)* @@ -129,9 +125,9 @@ Check the following: 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. @@ -139,9 +135,9 @@ Check the following: 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``. diff --git a/sphinx/tutorial/rose/applications.rst b/sphinx/tutorial/rose/applications.rst index e29b6c92e7..16677e6130 100644 --- a/sphinx/tutorial/rose/applications.rst +++ b/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 ` + weather-forecasting workflow in the + :ref:`Cylc tutorials ` 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 ` - into a standalone Rose application. + weather-forecasting workflow in the + :ref:`Cylc tutorials ` + 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 `: + The application gets three resources from different places: * The ``bin/forecast`` script. * The ``lib/python/util.py`` Python library. @@ -227,9 +227,7 @@ 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 ` - we set a few environment variables: + file in the weather-forecasting workflow we set a few environment variables: * ``WIND_FILE_TEMPLATE`` * ``WIND_CYCLES`` @@ -237,7 +235,7 @@ An application can be run using the :ref:`command-rose-app-run` command: * ``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. diff --git a/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst b/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst index f7d1d857c7..24783d35be 100644 --- a/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst +++ b/sphinx/tutorial/rose/furthertopics/date-time-manipulation.rst @@ -4,73 +4,69 @@ Date and Time Manipulation ========================== :term:`Datetime cycling ` suites inevitably involve -performing some form of datetime arithmetic. In the -:ref:`weather forecasting suite ` 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. diff --git a/sphinx/tutorial/rose/furthertopics/optional-configurations.rst b/sphinx/tutorial/rose/furthertopics/optional-configurations.rst index 03f592c430..6959c1d7b0 100644 --- a/sphinx/tutorial/rose/furthertopics/optional-configurations.rst +++ b/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: diff --git a/sphinx/tutorial/rose/rosie.rst b/sphinx/tutorial/rose/rosie.rst index 7e2c7fe072..c947f9b166 100644 --- a/sphinx/tutorial/rose/rosie.rst +++ b/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 ` + weather-forecasting suite from the :ref:`previous 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 ` + weather-forecasting suite from the :ref:`previous practical ` to a rosie repository, make some changes, and commit them to the repository. diff --git a/sphinx/tutorial/rose/suites.rst b/sphinx/tutorial/rose/suites.rst index da4f1c0df1..65bb503120 100644 --- a/sphinx/tutorial/rose/suites.rst +++ b/sphinx/tutorial/rose/suites.rst @@ -1,6 +1,3 @@ -.. include:: ../../hyperlinks.rst - :start-line: 1 - .. _tutorial-rose-suites: @@ -135,7 +132,7 @@ Using a Rose workflow configuration with Cylc 8 .. rubric:: In this tutorial we will create a Rose Suite Configuration for the - :ref:`weather-forecasting workflow`. + :ref:`weather-forecasting workflow`. .. _suites-practical: @@ -143,12 +140,11 @@ Using a Rose workflow configuration with Cylc 8 .. rubric:: In this tutorial we will create a Rose Suite Configuration for the - :ref:`weather-forecasting workflow`. + :ref:`weather-forecasting workflow`. #. **Create a new Cylc workflow** - Create a copy of the :ref:`weather-forecasting workflow - ` by running:: + Create a copy of the weather-forecasting workflow by running:: rose tutorial rose-suite-tutorial ~/cylc-src/rose-suite-tutorial cd ~/cylc-src/rose-suite-tutorial @@ -370,8 +366,7 @@ Rose Applications In Rose Suite Configurations .. rubric:: In this practical we will take the ``forecast`` Rose application that we developed in the :ref:`Metadata Tutorial ` - and integrate it into the :ref:`weather-forecasting workflow - `. + and integrate it into the weather-forecasting workflow. Move into the workflow source directory from the previous practical:: diff --git a/sphinx/tutorial/rose/summary.rst b/sphinx/tutorial/rose/summary.rst index c5b454ac52..5c8a87eef9 100644 --- a/sphinx/tutorial/rose/summary.rst +++ b/sphinx/tutorial/rose/summary.rst @@ -1,7 +1,3 @@ -.. include:: ../../hyperlinks.rst - :start-line: 1 - - .. _tutorial-rose-summary: Summary @@ -131,23 +127,23 @@ Suite Commands * :ref:`command-rose-app-run` * :ref:`command-rose-task-run` -Rose Utilities --------------- +Utilities +--------- -Rose contains some utilities to make life easier: +There are some utilities to make life easier: .. ifnotslides:: - :ref:`command-rose-date` + `isodatetime`_ A utility for parsing, manipulating and formatting date-times which is useful for working with the Cylc :term:`cycle point`: .. code-block:: console - $ rose date 2000 --offset '+P1Y1M1D' + $ isodatetime 2000 --offset '+P1Y1M1D' 2001-02-02T0000Z - $ rose date $CYLC_TASK_CYCLE_POINT --format 'The month is %B.' + $ isodatetime $CYLC_TASK_CYCLE_POINT --format 'The month is %B.' The month is April. See the :ref:`date-time tutorial ` @@ -155,14 +151,14 @@ Rose contains some utilities to make life easier: .. ifslides:: - ``rose date`` + ``isodatetime`` .. code-block:: console - $ rose date 2000 --offset '+P1Y1M1D' + $ isodatetime 2000 --offset '+P1Y1M1D' 2001-02-02T0000Z - $ rose date $CYLC_TASK_CYCLE_POINT --format 'The month is %B.' + $ isodatetime $CYLC_TASK_CYCLE_POINT --format 'The month is %B.' The month is April. Rose Built-In Applications