Update workflow config ref docs

cylc · Jul 20, 2022 · 00a0b3d · 00a0b3d
1 parent a94b53e
commit 00a0b3d
Showing 1 changed file with 19 additions and 29 deletions.
diff --git a/cylc/flow/cfgspec/workflow.py b/cylc/flow/cfgspec/workflow.py
@@ -59,15 +59,13 @@
 # Regex to check whether a string is a command
 REC_COMMAND = re.compile(r'(`|\$\()\s*(.*)\s*([`)])$')
 
-# Cylc8 Deprecation note.
 REPLACED_BY_PLATFORMS = '''
-.. warning::
+.. deprecated:: 8.0.0
 
-   .. deprecated:: 8.0.0
-
-   This will be removed in a future version of Cylc 8.
-
-   Use :cylc:conf:`flow.cylc[runtime][<namespace>]platform` instead.
+   This is used to select a matching platform.
+   It will be removed in a future version of Cylc 8.
+   Please set a suitable platform in
+   :cylc:conf:`flow.cylc[runtime][<namespace>]platform` instead.
 '''
 
 
@@ -1303,48 +1301,40 @@ def get_script_common_text(this: str, example: Optional[str] = None):
                     excluded by omission from an ``include`` list.
                 ''')
 
-            with Conf('job', desc=dedent('''
-                .. deprecated:: 8.0.0
-
+            with Conf('job', desc=REPLACED_BY_PLATFORMS + dedent('''
                 This section configures the means by which cylc submits task
                 job scripts to run.
-
-            ''') + REPLACED_BY_PLATFORMS):
+            ''')):
                 Conf('batch system', VDR.V_STRING, desc='''
-                    Batch/Queuing system to submit task jobs to.
-
                     .. deprecated:: 8.0.0
 
                        Kept for back compatibility but replaced by
                        :cylc:conf:`global.cylc[platforms][<platform name>]
                        job runner`.
+
+                    Batch/queuing system (aka job runner) to submit task
+                    jobs to.
                 ''')
                 Conf('batch submit command template', VDR.V_STRING, desc='''
-                    Override the default job submission command for the chosen
-                    batch system.
-
-                    .. seealso::
+                    .. deprecated:: 8.0.0
 
                        Kept for back compatibility but replaced by
                        :cylc:conf:`global.cylc[platforms][<platform name>]
                        job runner command template`.
-                ''')
 
-            with Conf('remote', desc=dedent('''
-                .. deprecated:: 8.0.0
+                    Override the default job submission command for the chosen
+                    batch system.
+                ''')
 
-            ''') + REPLACED_BY_PLATFORMS):
+            with Conf('remote', desc=REPLACED_BY_PLATFORMS):
                 Conf('host', VDR.V_STRING, desc=REPLACED_BY_PLATFORMS)
-                # TODO: Convert URL to a stable or latest release doc after 8.0
-                # https://github.com/cylc/cylc-flow/issues/4663
                 Conf('owner', VDR.V_STRING, desc="""
-                    This setting is obsolete at Cylc 8.
+                    .. warning::
 
-                    .. seealso::
+                       This setting is obsolete at Cylc 8.
 
-                       `Documentation on changes to remote owner
-                       <https://cylc.github.io/cylc-doc/latest/html/
-                       7-to-8/major-changes/remote-owner.html>`_
+                       See :ref:`documentation on changes to remote owner
+                       <728.remote_owner>`
                 """)
                 Conf('retrieve job logs', VDR.V_BOOLEAN,
                      desc=REPLACED_BY_PLATFORMS)