re

Author: wxtim

cylc/sphinx_ext/cylc_lang/__init__.py

@@ -222,11 +222,21 @@
          If you have a user config this will still override the site
          config!
 
+   ----
+   
+   Workflow Config
+   ^^^^^^^^^^^^^^^
+
    .. rst-example::
 
       .. cylc-metadata::
          :source: {workflow_path}
 
+   ----
+
+   Global Config
+   ^^^^^^^^^^^^^
+
    .. rst-example::
 
       .. cylc-metadata::

cylc/sphinx_ext/cylc_lang/autodocumenters.py

@@ -466,7 +466,8 @@ def get_global_metadata(config):
 
     @staticmethod
     def global_to_node(meta, src):
-        """Convert the global metadata into rst format."""
+        """Convert the global metadata into rst format.
+        """
         ret = [
             f'.. cylc:conf:: Global Config: {src}', '',
             f'{INDENT}.. note::', '',
@@ -490,26 +491,47 @@ def global_to_node(meta, src):
                         f'{INDENT * 3}.. cylc:conf:: {title}', '',
                         f'{INDENT * 4}.. csv-table:: Key Details', '']
 
+                    # Add the definition regex if an explicit title
+                    # has been given to the platform.
                     if title != regex:
                         ret.append(f'{INDENT * 5}Regex, ``{regex}``.')
 
                     if info.get('job_runner'):
                         ret.append(
                             f'{INDENT * 5}job runner,'
                             f' ``{info.get("job_runner")}``')
-
+                    
+                    # Lists platforms in group or hosts in platform.
                     selectables = '- ' + '\n- '.join(
                         f'``{i}``' for i in info["select_from"])
-                    ret.append(f'{INDENT * 5}{selects},"{selectables}"')
+                    ret += [f'{INDENT * 5}{selects},"{selectables}"', '']
+
                     ret.append('')
-                    desc = platform_meta.get("description", "No description")
+                    url = platform_meta.get('url', '')
+                    if url:
+                        ret += [
+                            f'{INDENT * 4}.. seealso::',
+                            '',
+                            f'{INDENT * 5}{url}',
+                            ''
+                        ]
+
+                    # Add description.
+                    desc = platform_meta.get("description", "")
                     ret += [
                         f'{INDENT * 4}'
                         f'{desc}',
                         '']
 
-        [print(i) for i in ret]
-        
+                    # Add any other metadata as a definition list:
+                    ret += CylcMetadataDirective.meta_to_def_list(
+                        metadata=platform_meta.items(),
+                        lowest_indent=4
+                    )
+
+        # Handy for debugging:
+        # [print(f'{i + 1:03}|{j}') for i, j in enumerate(ret)]
+
         return ret
 
     @staticmethod
@@ -577,30 +599,47 @@ def get_workflow_metadata(config, conf_path):
 
     @staticmethod
     def workflow_to_node(meta, src):
-        """Convert workflow metadata to RST.
+        """Convert workflow metadata to list of strings for use as a node.
 
         """
-
-        # ret = [
-        #     f'.. {directive}::{" " if arguments else ""}{" ".join(arguments)}'
-        # ]
-        # rst = Doc()
-
-        # # Handle the workflow config metadata:
-        # CylcMetadataDirective.write_section(rst, meta.get('workflow', {}), '#')
-
-        # # Handle the runtime config metadata:
-        # rst.append('Runtime', '=')
-        # for taskmeta in meta['runtime'].values():
-        #     CylcMetadataDirective.write_section(rst, taskmeta)
         ret = []
 
+        # Handle the workflow config metadata:
         workflow_title = meta.get('workflow', {}).get('title', src)
-        ret.append(f'.. cylc:conf:: {workflow_title}')
-        ret.append('')
         workflow_desc = meta.get('workflow', {}).get(
-            'description', 'No Description').split('\n')
-        ret += [f'   {t.strip()}' for t in workflow_desc]
+            'description', '').split('\n')
+
+        ret += [f'.. cylc:conf:: {workflow_title}', '']
+        ret += [f'   {t.strip()}' for t in workflow_desc] + ['']
+
+        # Handle the runtime config metadata:
+        ret += [f'{INDENT}Runtime', f'{INDENT}=======', '']
+
+        for taskmeta in meta['runtime'].values():
+            indent = INDENT
+            title = taskmeta["title"]
+            ret += [f'{indent}.. cylc:conf:: {title}', '']
+            indent += INDENT
+
+            url = taskmeta.get('url', '')
+            if url:
+                ret += [
+                    f'{indent}.. seealso::',
+                    '',
+                    f'{indent + INDENT}{url}',
+                    ''
+                ]
+
+            desc = taskmeta.get('description', '').replace('\n', ' ')
+            ret += [f'{indent}{desc}', '']
+
+        ret += CylcMetadataDirective.meta_to_def_list(
+            metadata=taskmeta.items(),
+            lowest_indent=1
+        )
+
+        # Handy for debugging:
+        # [print(f'{i + 1:03}|{j}') for i, j in enumerate(ret)]
 
         return ret
 
@@ -622,3 +661,22 @@ def check_subproc_output(sub):
                 msg += '\n'.join(
                     i.strip("\n") for i in sub.stderr.decode().split('\n'))
                 raise Exception(msg)
+
+    @staticmethod
+    def meta_to_def_list(metadata, lowest_indent):
+        result = []
+        other_meta_items = False
+        for key, value in metadata:
+            if key in ['title', 'description', 'url']:
+                continue
+            if other_meta_items is False:
+                result += [
+                    f'{INDENT * lowest_indent}Other metadata',
+                    f'{INDENT * lowest_indent}^^^^^^^^^^^^^^', '']
+                other_meta_items = True
+            value = value.replace('\n', ' ')
+            result += [
+                f'{INDENT * (lowest_indent + 1)}{key}:',
+                f'{INDENT * (lowest_indent + 2)}{value}', '']
+
+        return result

etc/flow.cylc

@@ -29,8 +29,7 @@
     [[bar]]
         [[[meta]]]
             description = """
-                What should happen if I forget the title?
-                Should I process RST?
+                Lorem Ipsum blah blah blah
             """
             url = 'https://www.myproject.com/tasks/bar'
-            see also = Bar task docs.
+            and another thing = Morse

etc/flow/global.cylc

@@ -6,11 +6,20 @@
                 If platform name is a regex you might want
                 an explicit title
             """
+            url = https://www.mysupercomputer.ac.uk
     [[mornington_crescent]]
         [[[meta]]]
             description = """
                 I win!
             """
+            location = Otago
+            contractor = Takahē Industries
+            other info = """
+                This is a longer
+                chunk of metadata designed
+                to see if the extra section
+                handling can manage.
+            """
     [[camden_town]]
         hosts = northern, buslink
         job runner = pbs