Merge pull request #2387 from challurip/suite-meta

Put suite metadata items in a meta section

bin/cylc-documentation

@@ -128,7 +128,7 @@ def main():
         else:
             # Suite documentation.
             res, stdout = run_get_stdout(
-                "cylc get-suite-config -i URL %s" % suite)
+                "cylc get-suite-config -i [meta]URL %s" % suite)
         if not res:
             # (Illegal config item)
             sys.exit(stdout)

dev/suites/busy/suite.rc

@@ -1,8 +1,9 @@
 #!jinja2
-title = Suite-1000-x3
-description = A suite of 1000 tasks per cycle
+[meta]
+    title = Suite-1000-x3
+    description = A suite of 1000 tasks per cycle
 [cylc]
-    UTC mode = True # Ignore DST
+    UTC mode = True  # Ignore DST
 [scheduling]
     initial cycle point = 20130101T00
     final cycle point = 20130103T00

dev/suites/busy_param/suite.rc

@@ -1,7 +1,8 @@
-title = Suite-1000-x3
-description = A suite of 1000 tasks per cycle
+[meta]
+    title = Suite-1000-x3
+    description = A suite of 1000 tasks per cycle
 [cylc]
-    UTC mode = True # Ignore DST
+    UTC mode = True  # Ignore DST
     [[parameters]]
         i = 0..9
         j = 0..9

dev/suites/complex/suite.rc

@@ -9,9 +9,9 @@
 {% if not sleep_time is defined %}
     {% set sleep_time = 1 %}
 {% endif %}
-
-title = "Complex Suite Demo"
-description = "This is a super-elaborate obfuscated version of a suite with no Jinja2 to condense it down."
+[meta]
+    title = "Complex Suite Demo"
+    description = "This is a super-elaborate obfuscated version of a suite with no Jinja2 to condense it down."
 [cylc]
     UTC mode = True
     [[events]]

dev/suites/dave/suite.rc

@@ -1,8 +1,8 @@
 #!jinja2
-
-title = "Dave's evil load test"
-description = """This is the suite that motivated the move to
-(a) multi-threaded Pyro daemon; (b) continuous request handling in a 
+[meta]
+    title = "Dave's evil load test"
+    description = """This is the suite that motivated the move to
+(a) multi-threaded Pyro daemon; (b) continuous request handling in a
 background thread; (c) job submission in a background worker thread."""
 
 {% set N_LOCAL = 10 %}

dev/suites/mshin/suite.rc

@@ -1,8 +1,8 @@
 #!jinja2
+[meta]
+    title = "Matt Shin's 1000 task example with slow parsing"
 
-title = "Matt Shin's 1000 task example with slow parsing"
-
-description = """This suite motivated some optimization of config
+    description = """This suite motivated some optimization of config
 parsing and task proxy definition, resulting in a speed up factor 
 of 2 to 3 for suite validation."""
 

doc/src/cylc-user-guide/cug.tex

@@ -1869,7 +1869,8 @@ \subsection{Jinja2}
 \end{lstlisting}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = "A Jinja2 Hello World! suite"
+[meta]
+    title = "A Jinja2 Hello World! suite"
 [scheduling]
     [[dependencies]]
         graph = "hello"
@@ -1885,7 +1886,8 @@ \subsection{Jinja2}
 \end{lstlisting}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = "A Jinja2 Hello World! suite"
+[meta]
+    title = "A Jinja2 Hello World! suite"
 [scheduling]
     [[dependencies]]
         graph = "hello => BYE"
@@ -2256,7 +2258,8 @@ \subsection{Scheduling - Dependency Graphs}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = "Dependency Example 1"
+[meta]
+    title = "Dependency Example 1"
 [cylc]
     UTC mode = True
 [scheduling]
@@ -2445,7 +2448,8 @@ \subsubsection{Graph Types}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = some one-off tasks
+[meta]
+    title = some one-off tasks
 [scheduling]
     [[dependencies]]
         graph = "foo => bar & baz => qux"
@@ -2471,7 +2475,8 @@ \subsubsection{Graph Types}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = some cycling tasks
+[meta]
+    title = some cycling tasks
 # (no dependence between cycle points)
 [scheduling]
     [[dependencies]]
@@ -3266,8 +3271,9 @@ \subsubsection{Trigger Types}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = automated failure recovery
-description = """
+[meta]
+    title = automated failure recovery
+    description = """
 Model task failure triggers diagnosis
 and recovery tasks, which take themselves
 out of the suite if model succeeds. Model
@@ -5130,9 +5136,11 @@ \subsubsection{Jinja2 Default Values And Template Inputs}
 \begin{lstlisting}
 #!Jinja2
 
-title = "Jinja2 example: use of defaults and external input"
+[meta]
 
-description = """
+    title = "Jinja2 example: use of defaults and external input"
+
+    description = """
 The template variable FIRST_TASK must be given on the cylc command line
 using --set or --set-file=FILE; two other variables, LAST_TASK and
 N_MEMBERS can be set similarly, but if not they have default values."""

doc/src/cylc-user-guide/suiterc.tex

@@ -13,39 +13,50 @@ \subsection{Top Level Items}
 The only top level configuration items at present are the suite title
 and description.
 
-\subsubsection{title}
+\subsubsection{group}
 
-A single line description of the suite. It is displayed in the db viewer
-window and can be retrieved at run time with the
+A single line group name for a suite. It is displayed in the gscan
+window and can be used as a way of grouping related suites together.
 \lstinline=cylc show= command.
 
 \begin{myitemize}
 \item {\em type:} single line string
 \item {\em default:} (none)
 \end{myitemize}
 
-\subsubsection{description}
 
-A multi-line description of the suite. It can be retrieved by the db viewer
-right-click menu, or at run time with the \lstinline=cylc show= command.
+\subsection{[meta]}
+
+Section containing metadata items for this suite. Several items
+(title, description, URL) are pre-defined and are used by the GUI. Others can be 
+user-defined and passed to suite event handlers to be interpreted according to your 
+needs. For example, the value of a ``suite-priority'' item could determine how an event 
+handler responds to failure events.
+
+
+\subsubsection[title]{ [meta] \textrightarrow title}
+
+A single line description of the suite. It is displayed in the GUI ``Open Another Suite''
+window and can be retrieved at run time with the
+\lstinline=cylc show= command.
 
 \begin{myitemize}
-\item {\em type:} multi-line string
+\item {\em type:} single line string
 \item {\em default:} (none)
 \end{myitemize}
 
-\subsubsection{group}
+\subsubsection[description]{ [meta] \textrightarrow description}
 
-A single line group name for a suite. It is displayed in the gscan
-window and can be used as a way of grouping related suites together.
+A multi-line description of the suite. It can be retrieved at run time with the
 \lstinline=cylc show= command.
 
 \begin{myitemize}
-\item {\em type:} single line string
+\item {\em type:} multi-line string
 \item {\em default:} (none)
 \end{myitemize}
 
-\subsubsection{URL} \label{SuiteURL}
+\subsubsection[URL]{ [meta] \textrightarrow URL}
+\label{SuiteURL}
 
 A web URL to suite documentation.  If present it can be browsed with the
 \lstinline=cylc doc= command, or from the gcylc Suite menu.  The variable
@@ -59,6 +70,22 @@ \subsubsection{URL} \label{SuiteURL}
 \item {\em example:} \lstinline=http://suites/${CYLC_SUITE_NAME}/index.html=
 \end{myitemize}
 
+\subsubsection[\_\_MANY\_\_]{ [meta] \textrightarrow \_\_MANY\_\_}
+
+Replace \_\_MANY\_\_ with any user-defined metadata item. These, like title, URL, etc. can be passed
+to suite event handlers to be interpreted according to your needs. For example, ``suite-priority''.
+
+\begin{myitemize}
+\item {\em type:} String or integer
+\item {\em default:} (none)
+\item {\em example:}
+    \begin{lstlisting}
+[meta]
+    suite-priority = high
+    \end{lstlisting}
+\end{myitemize}
+
+
 \subsection{[cylc]}
 
 This section is for configuration that is not specifically task-related.
@@ -315,6 +342,12 @@ \subsection{[cylc]}
     \item \%(message)s: event message, if any
 \end{myitemize}
 
+It can also include the patterns from the [meta] section of the suite, for example:
+\begin{myitemize}
+    \item \%(suite-priority)s: suite priority
+    \item \%(color)s: suite color
+\end{myitemize}
+
 Otherwise, the command line will be called with the following command line
 arguments:
 \begin{lstlisting}
@@ -1234,10 +1267,20 @@ \subsection{[runtime]}
 Section containing metadata items for this task or family namespace. Several items
 (title, description, URL) are pre-defined and are used by the GUI. Others can be 
 user-defined and passed to task event handlers to be interpreted according to your 
-needs. For example, the value of an "importance" item could determine how an event 
+needs. For example, the value of an ``importance'' item could determine how an event 
 handler responds to task failure events.
 
-\paragraph[title]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow title}
+Any suite meta item can now be passed to task event handlers by prefixing the
+string template item name with ``suite\_'', for example : 
+
+\begin{lstlisting}
+[runtime]
+    [[root]]
+        [[[events]]]
+            failed handler = send-help.sh %(suite_title)s %(suite_importance)s %(title)s
+\end{lstlisting}
+
+\subparagraph[title]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow title}
 
 A single line description of this namespace. It is displayed by the
 \lstinline=cylc list= command and can be retrieved from running tasks
@@ -1248,7 +1291,7 @@ \subsection{[runtime]}
 \item {\em root default:} (none)
 \end{myitemize}
 
-\paragraph[description]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow description}
+\subparagraph[description]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow description}
 
 A multi-line description of this namespace, retrievable from running tasks with the
 \lstinline=cylc show= command.
@@ -1258,7 +1301,7 @@ \subsection{[runtime]}
 \item {\em root default:} (none)
 \end{myitemize}
 
-\paragraph[URL]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow URL}
+\subparagraph[URL]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow URL}
 \label{TaskURL}
 
 A web URL to task documentation for this suite.  If present it can be browsed
@@ -1284,7 +1327,7 @@ \subsection{[runtime]}
 (Note that URLs containing the suite comment delimiter
 \lstinline=#= must be protected by quotes).
 
-\paragraph[\_\_MANY\_\_]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow \_\_MANY\_\_}
+\subparagraph[\_\_MANY\_\_]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow \_\_MANY\_\_}
 
 Replace \_\_MANY\_\_ with any user-defined metadata item. These, like title, URL, etc. can be passed
 to task event handlers to be interpreted according to your needs. For example, the value of an
@@ -1594,12 +1637,18 @@ \subsection{[runtime]}
     \item \%(message)s: event message, if any
 \end{myitemize}
 
-Can also include the patterns from [[[meta]]] section of the task, for example:
+The template can also include the patterns from [[[meta]]] section of the task, for example:
 \begin{myitemize}
     \item \%(importance)s: task priority
     \item \%(color)s: task color
 \end{myitemize}
 
+Patterns from the [meta] section of the suite can also be used, for example:
+\begin{myitemize}
+    \item \%(suite\_priority)s: suite priority
+    \item \%(suite\_color)s: suite color
+\end{myitemize}
+
 Otherwise, the command line will be called with the following arguments:
 \begin{lstlisting}
 <task-event-handler> %(event)s %(suite)s %(id)s %(message)s

examples/AutoRecover/CleanupTask/suite.rc

@@ -1,6 +1,7 @@
-title = family failure cleanup task example number 1
+[meta]
+    title = family failure cleanup task example number 1
 
-description = """
+    description = """
 Illustrates use of a special task to clean up failed tasks. Here the
 cleanup task runs whether or not the family fails, but it only cleans up
 if necessary. See also family failure cleanup task example number 2, and

examples/AutoRecover/EventHook/suite.rc

@@ -1,6 +1,7 @@
-title = "family failure task event hook example"
+[meta]
+    title = "family failure task event hook example"
 
-description = """
+    description = """
 Illustrates use of a task event hook script to clean up failed tasks."""
 
 [scheduling]

examples/AutoRecover/suicide/suite.rc

@@ -1,6 +1,7 @@
-title = "automated failure recovery example"
+[meta]
+    title = "automated failure recovery example"
 
-description = """
+    description = """
 Model task failure triggers diagnosis and recovery tasks, which
 otherwise take themselves out of the suite if model succeeds.
 Model post processing triggers off model or recovery tasks."""

examples/AutoRecover/suicide2/suite.rc

@@ -1,5 +1,5 @@
-
-description = """
+[meta]
+    description = """
 A triple check-and-retry suite. This could be use of the main task VAR
 sometimes fails to do its job without actually reporting failure. Of
 course it would be better to fix VAR (get it to report failure properly)

examples/clock-expire/suite.rc

@@ -1,5 +1,6 @@
-title = task expire example suite
-description = """
+[meta]
+    title = task expire example suite
+    description = """
 Skip a daily post-processing workflow if the 'copy' task has expired."""
 
 [cylc]

examples/cycling/Monthly/suite.rc

@@ -1,7 +1,8 @@
-title = "climate model run"
-description = """
-    A climate model run with an monthly restart cycle, archiving every 6 month and
-    post-processing every 12 months.
+[meta]
+    title = "climate model run"
+    description = """
+        A climate model run with an monthly restart cycle, archiving every 6 month and
+        post-processing every 12 months.
               """
 [scheduling]
     initial cycle point = 2010-01  # Note: '201001' is not permitted.

examples/family/extra/suite.rc

@@ -1,6 +1,7 @@
-title = "A complex task family example"
+[meta]
+    title = "A complex task family example"
 
-description = "Task families with family and extra-family dependencies."
+    description = "Task families with family and extra-family dependencies."
 
 [scheduling]
     initial cycle point = 20110101T12

examples/family/triggering/suite.rc

@@ -1,6 +1,7 @@
-title = "family triggering test suite"
+[meta]
+    title = "family triggering test suite"
 
-description = """
+    description = """
 For manual testing of new-style family triggers. Play around
 with script true/false to get different outcomes."""