Merge pull request #853 from jfrost-mo/job_script_environment_variables

Improve Job Script Environment Variables reference

Author: oliver-sanders

CONTRIBUTING.md

@@ -57,6 +57,7 @@ requests_).
  - Scott Wales
  - Elliot Fontaine
  - Mark Dawson
+ - James Frost
 <!-- end-shortlog -->
 
 (All contributors are identifiable with email addresses in the git version

src/dictionaries/proper_nouns

@@ -14,6 +14,7 @@ Gantt
 Gedit
 Graphene
 Graphviz
+Gregorian
 GScan
 Heathrow
 Hoverwork

src/dictionaries/words

@@ -8,6 +8,7 @@ auth
 authenticator
 authoriser
 backticks
+basename
 baz
 boolean
 booleans
@@ -51,6 +52,7 @@ freeform
 fullmatch
 globals
 graining
+gregorian
 gscan
 hardcodes
 hardwired
@@ -81,6 +83,7 @@ kwarg
 kwargs
 latin
 lifecycle
+linearised
 linearization
 linter
 linting
@@ -100,6 +103,7 @@ obs
 offline
 onwards
 packjob
+param
 parameterization
 parameterize
 parameterized
@@ -108,10 +112,12 @@ passX
 passphrase
 passwordless
 performant
+pings
 placeholder
 placeholders
 plugin
 plugins
+postproc
 postprocessing
 pre
 predated

src/reference/job-script-vars/index.rst

@@ -4,9 +4,7 @@ Job Script Environment Variables
 These environment variables provided by the :term:`scheduler` are available
 to Cylc job scripts at run time:
 
-.. literalinclude:: var-list.txt
-   :language: sub
-
+.. include:: var-list.rst
 
 .. seealso::
 

src/reference/job-script-vars/var-list.rst

@@ -0,0 +1,116 @@
+CYLC_VERSION
+    Version of cylc installation used
+
+CYLC_VERBOSE
+    Verbose mode, true or false
+
+CYLC_DEBUG
+    Debug mode (even more verbose), true or false
+
+CYLC_CYCLING_MODE
+    Cycling mode, e.g. "gregorian" or "integer"
+
+ISODATETIMECALENDAR
+    Calendar mode for the ``isodatetime`` command, defined with the value of
+    CYLC_CYCLING_MODE when in any datetime cycling mode
+
+CYLC_UTC
+    UTC mode, True or False
+
+TZ
+    Set to "UTC" in UTC mode or not defined
+
+CYLC_WORKFLOW_INITIAL_CYCLE_POINT
+    Initial cycle point
+
+CYLC_WORKFLOW_FINAL_CYCLE_POINT
+    Final cycle point
+
+CYLC_WORKFLOW_ID
+    Workflow ID e.g. "foo/run1" or "a/b/c/run1"
+
+CYLC_WORKFLOW_NAME
+    Workflow ID with the run name removed (use CYLC_WORKFLOW_ID for most
+    purposes) e.g. "foo" or "a/b/c"
+
+CYLC_WORKFLOW_NAME_BASE
+    The basename of the workflow name (use CYLC_WORKFLOW_ID for most purposes)
+    e.g. "foo" or "c"
+
+CYLC_WORKFLOW_UUID
+    Workflow UUID string
+
+CYLC_WORKFLOW_HOST
+    Host running the workflow process
+
+CYLC_WORKFLOW_OWNER
+    User ID running the workflow process
+
+CYLC_WORKFLOW_RUN_DIR
+    Location of the run directory in job host, e.g. ~/cylc-run/foo/run1
+
+CYLC_WORKFLOW_LOG_DIR
+    Location of the scheduler's log files, e.g.
+    ~/cylc-run/foo/run1/log/scheduler
+
+CYLC_WORKFLOW_SHARE_DIR
+    Workflow (or task!) shared directory e.g. ~/cylc-run/foo/run1/share
+
+CYLC_WORKFLOW_WORK_DIR
+    Workflow work directory, e.g. ~/cylc-run/foo/run1/work
+
+CYLC_TASK_JOB
+    Job identifier expressed as CYCLE-POINT/TASK-NAME/SUBMIT-NUMBER e.g.
+    20110511T1800Z/t1/01
+
+CYLC_TASK_ID
+    Task instance identifier CYCLE-POINT/TASK-NAME e.g. 20110511T1800Z/t1
+
+CYLC_TASK_NAME
+    Job's task name, e.g. t1
+
+CYLC_TASK_CYCLE_POINT
+    Cycle point, e.g. 20110511T1800Z
+
+ISODATETIMEREF
+    Reference time for the ``isodatetime`` command, defined with the value of
+    CYLC_TASK_CYCLE_POINT when in any datetime cycling mode
+
+CYLC_TASK_SUBMIT_NUMBER
+    Job's submit number, e.g. 1, increments with every submit
+
+CYLC_TASK_TRY_NUMBER
+    Number of execution tries, e.g. 1 increments with automatic execution retry
+    delays.
+
+CYLC_TASK_FLOW_NUMBERS
+    Flows this task belongs to, e.g. 1,2
+
+CYLC_TASK_LOG_DIR
+    Location of the job log directory e.g.
+    ~/cylc-run/foo/run1/log/job/20110511T1800Z/t1/01/
+
+CYLC_TASK_LOG_ROOT
+    The job script path e.g.
+    ~/cylc-run/foo/run1/log/job/20110511T1800Z/t1/01/job
+
+CYLC_TASK_SHARE_CYCLE_DIR
+    Cycle point-specific shared directory for this task. e.g.
+    ~/cylc-run/foo/run1/share/cycle/20110511T1800Z
+
+CYLC_TASK_WORK_DIR
+    Location of task work directory (see below) e.g.
+    ~/cylc-run/foo/run1/work/20110511T1800Z/t1
+
+CYLC_TASK_NAMESPACE_HIERARCHY
+    Linearised family namespace of the task, e.g. root postproc t1
+
+CYLC_TASK_COMMS_METHOD
+    Set to "ssh" if communication method is "ssh"
+
+CYLC_TASK_SSH_LOGIN_SHELL
+    With "ssh" communication, if set to "True", use login shell on workflow host
+
+CYLC_TASK_PARAM\_\<param\>
+    If this task is a parameterized task, the value of the parameter named
+    \<param\>

src/reference/job-script-vars/var-list.txt

@@ -159,7 +159,7 @@ installed workflow at run time:
 .. table::
 
    =======================    ==============
-   CYLC_WORKFLOW_LOG_DIR      Workflow log sub-directory
+   CYLC_WORKFLOW_LOG_DIR      Workflow scheduler's log directory
    CYLC_WORKFLOW_SHARE_DIR    Workflow share sub-directory
    CYLC_WORKFLOW_WORK_DIR     Workflow work sub-directory
    =======================    ==============

src/user-guide/writing-workflows/jinja2.rst

@@ -291,8 +291,7 @@ Job Script Variables
 These variables provided by the :term:`scheduler` are available to
 :term:`job scripts <job script>`:
 
-.. literalinclude:: ../../reference/job-script-vars/var-list.txt
-   :language: sub
+.. include:: ../../reference/job-script-vars/var-list.rst
 
 Some global shell variables are also defined in the job script, but not
 exported to subshells: