Merge pull request #545 from cylc/8.0.x

8.0.x

Author: MetRonnie

src/7-to-8/major-changes/cylc-install.rst

@@ -93,8 +93,9 @@ the :term:`run directory` to the install target.
 
 If you have used Rose 2019, you may be used to all files and directories in
 the run directory being included.
-However, Cylc 8 will only copy the ``app``, ``bin``, ``etc`` and ``lib``
-directories by default (in addition to authentication files in ``.service``).
+However, Cylc 8 will only copy the ``ana``, ``app``, ``bin``, ``etc`` and
+``lib`` directories by default (in addition to authentication files in
+``.service``).
 If you want to include custom files and directories in remote installation,
 use :cylc:conf:`flow.cylc[scheduler]install`.
 

src/7-to-8/summary.rst

@@ -46,6 +46,11 @@ take action on any warnings.
 .. TODO Add ref to breaking changes section within Major changes, once created,
    including optional ouputs.
 
+.. note::
+
+   Validation warnings use a :ref:`shorthand notation<config_item_shorthand>`
+   to refer to nested configuration settings on a single line, like this:
+   ``[section][sub-section]item``.
 
 
 New Web and Terminal UIs

src/dictionaries/proper_nouns

@@ -1,4 +1,5 @@
 Aldergrove
+ana
 Boolean
 Booleans
 Camborne

src/dictionaries/words

@@ -31,6 +31,7 @@ dirs
 duration
 durations
 env
+etc
 executables
 facade
 filename
@@ -146,7 +147,7 @@ runnable
 runtime
 schd
 screenshot
-setups
+setup
 setups
 shebang
 shutdown

src/hyperlinks.rst.include

@@ -9,7 +9,7 @@
 .. _Cylc Discourse Forum (7-to-8 topic): https://cylc.discourse.group/c/cylc/7-to-8/13
 .. _DataPoint: https://www.metoffice.gov.uk/services/data/datapoint
 .. _Discourse: https://cylc.discourse.group/
-.. _EmPy: http://www.alcyone.com/software/empy/
+.. _EmPy: https://pypi.org/project/empy/
 .. _FCM User Guide: http://metomi.github.io/fcm/doc/user_guide/
 .. _FCM: https://metomi.github.io/fcm/doc/
 .. _INI: https://en.wikipedia.org/wiki/INI_file

src/plugins/install/index.rst

@@ -35,7 +35,7 @@ In this example a pre-configure plugin which logs a "Hello World" message
 and, after installation, logs some info about the installation:
 
 .. code-block:: python
-   :caption: my_plugin.py
+   :caption: ``my_plugin.py``
 
    from cylc.flow import LOG
 
@@ -54,7 +54,7 @@ Plugins are registered by registering them with the ``cylc.pre_configure``
 and ``cylc.post_install`` entry points:
 
 .. code-block:: python
-   :caption: setup.py
+   :caption: ``setup.py``
 
    # plugins must be properly installed, in-place PYTHONPATH meddling will
    # not work.

src/reference/config/file-format.rst

@@ -158,23 +158,19 @@ Include-files
    :ref:`Jinja2's <Jinja>` template inclusion mechanism can be used with Cylc
    too.
 
+.. _config_item_shorthand:
 
 Shorthand
 ---------
 
-Throughout the documentation we refer to configuration settings in the
-following way:
-
-``[section]``
-   An entire section.
-``[section]setting``
-   A setting within a section.
-``[section]setting=value``
-   The value of a setting within a section.
-``[section][sub-section]another-setting``
-   A setting within a sub-section.
-
-.. warning::
-   We only use one set of square brackets at each level when writing nested
-   sections on one line like this. But in the file, each sub-section
-   gets additional square brackets as shown above.
+.. include:: shorthand.rst
+
+.. code-block:: cylc
+
+   # This:
+   #   [runtime][task-a][environment]FOO = foo
+   # Means:
+   [runtime]
+       [[task-a]]
+           [[[environment]]]
+               FOO = foo

src/reference/config/shorthand.rst

@@ -0,0 +1,12 @@
+We often use a compact single-line notation to refer to nested config items:
+
+``[section]``
+   An entire section.
+``[section]setting``
+   A setting within a section.
+``[section]setting=value``
+   The value of a setting within a section.
+``[section][sub-section]another-setting``
+   A setting within a sub-section.
+
+In the file, however, section headings need additional brackets at each level.

src/tutorial/scheduling/graphing.rst

@@ -58,18 +58,7 @@ Example
 Shorthand
 ^^^^^^^^^
 
-Throughout this tutorial we will refer to configuration settings in the following ways:
-
-``[section]``
-   An entire section.
-``[section]key``
-   A specific config item, within a section.
-``[section]key=value``
-   The value of a specific config item, within a section.
-``[section][sub-section]another-key``
-   Note we only use one set of square brackets per section heading when
-   writing on one line like this. In the config file each nested level
-   gets another set of square brackets.
+.. include:: ../../reference/config/shorthand.rst
 
 Duplicate Items
 ^^^^^^^^^^^^^^^

src/user-guide/running-workflows/scheduler-start-up.rst

@@ -169,10 +169,16 @@ files and directories required to run jobs, including authentication keys
 
 The default directories included in the remote install are:
 
-* ``app/``
-* ``bin/``
-* ``etc/``
-* ``lib/``
+``ana/``
+   For workflow-level :ref:`builtin.rose_ana` analysis modules.
+``app/``
+   For :ref:`Rose Applications`.
+``bin/``
+   For scripts and executables to be run by tasks.
+``etc/``
+   For miscellaneous resources.
+``lib/``
+   For shared libraries e.g. :ref:`CustomJinja2Filters`.
 
 These will be transferred from the workflow run directory on the
 :term:`scheduler` host to the remote host.