From 3ae39c84c446e479af256e4725a6b2a845c6f9c0 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Wed, 21 Aug 2024 16:43:38 +0100
Subject: [PATCH] fix

---
 cylc/sphinx_ext/cylc_lang/__init__.py        |  8 +++
 cylc/sphinx_ext/cylc_lang/autodocumenters.py | 60 ++++++++++++++++----
 etc/flow/global.cylc                         |  1 +
 3 files changed, 57 insertions(+), 12 deletions(-)

diff --git a/cylc/sphinx_ext/cylc_lang/__init__.py b/cylc/sphinx_ext/cylc_lang/__init__.py
index 918c827..0c1505b 100644
--- a/cylc/sphinx_ext/cylc_lang/__init__.py
+++ b/cylc/sphinx_ext/cylc_lang/__init__.py
@@ -219,6 +219,11 @@
    .. rst-example::
 
       .. auto-cylc-global:: {workflow_path}
+         :show:
+            foo,
+            install target,
+            bar,
+            qax
 
 .. rst:directive:: .. auto-cylc-workflow:: source
 
@@ -227,6 +232,9 @@
    .. rst-example::
 
       .. auto-cylc-workflow:: {workflow_path}/workflow
+         :show:
+            foo,
+            platform
 """
 
 
diff --git a/cylc/sphinx_ext/cylc_lang/autodocumenters.py b/cylc/sphinx_ext/cylc_lang/autodocumenters.py
index 4f0ef35..5b36cca 100644
--- a/cylc/sphinx_ext/cylc_lang/autodocumenters.py
+++ b/cylc/sphinx_ext/cylc_lang/autodocumenters.py
@@ -28,7 +28,7 @@
 )
 from typing import Any, Dict, List, Optional
 
-from docutils.parsers.rst import Directive
+from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import StringList, ViewList
 
 from sphinx import addnodes, project
@@ -397,10 +397,17 @@ class CylcGlobalDirective(SphinxDirective):
     """Represent a Cylc Global Config.
     """
     optional_arguments = 1
+    option_spec = {
+        'show': directives.split_escaped_whitespace
+    }
 
     def run(self):
+        display_these = None
+        if 'show' in self.options:
+            display_these = [
+                i.strip() for i in self.options['show'][0].split(',')]
         src = self.arguments[0] if self.arguments else None
-        ret = self.config_to_node(load_cfg(src), src)
+        ret = self.config_to_node(load_cfg(src), src, display_these)
         node = addnodes.desc_content()
         self.state.nested_parse(
             StringList(ret),
@@ -410,7 +417,11 @@ def run(self):
         return [node]
 
     @staticmethod
-    def config_to_node(config: [Dict, Any], src: str) -> List[str]:
+    def config_to_node(
+        config: [Dict, Any],
+        src: str,
+        display_these=None,
+    ) -> List[str]:
         """Take a global config and create a node for display.
 
         * Displays `platform groups` and then `platforms`.
@@ -482,13 +493,13 @@ def config_to_node(config: [Dict, Any], src: str) -> List[str]:
                 # Custom keys:
                 section_content += custom_items(meta)
 
-                # Key list needs a closing space:
-                section_content.append('')
+                if display_these:
+                    section_content += custom_items(conf, these=display_these)
 
                 # Add description tag.
                 description = meta.get('description', '')
                 if description:
-                    section_content.append(description)
+                    section_content += ['', description, '']
 
                 content += directive(
                     CYLC_CONF, [title], content=section_content)
@@ -510,11 +521,19 @@ class CylcWorkflowDirective(SphinxDirective):
     """Represent a Cylc Workflow Config.
     """
     required_arguments = 1
+    option_spec = {
+        'show': directives.split_escaped_whitespace
+    }
 
     def run(self):
+        display_these = None
+        if 'show' in self.options:
+            display_these = [
+                i.strip() for i in self.options['show'][0].split(',')]
         ret = self.config_to_node(
             load_cfg(self.arguments[0]),
-            self.arguments[0]
+            self.arguments[0],
+            display_these
         )
         node = addnodes.desc_content()
         self.state.nested_parse(
@@ -525,7 +544,7 @@ def run(self):
         return [node]
 
     @staticmethod
-    def config_to_node(config, src):
+    def config_to_node(config, src, display_these=None):
         """Document Workflow
 
         Additional processing:
@@ -573,6 +592,10 @@ def config_to_node(config, src):
             # Custom keys:
             task_content += custom_items(task_meta)
 
+            # Config keys given
+            if display_these:
+                task_content += custom_items(taskdef, display_these)
+
             desc = task_meta.get('description', '')
             if desc:
                 task_content += ['', desc, '']
@@ -651,16 +674,29 @@ def custom_items(
         data: The input dictionary.
         not_these: Keys to ignore.
         these: Keys to include.
+
+    Examples:
+        >>> data = {'foo': 'I cannot believe it!', 'title': 'Hi'}
+        >>> custom_items(data)
+        :foo:
+           I cannot believe it!
+        >>> custom(data, these=['title'])
+        :title:
+           Hi
     """
     ret = []
     if these:
         for key in these:
-            value = data.get('key', '')
-            value = value.replace("\n", "\n   ")
-            ret.append(f':{key}:\n   {value}')
+            value = data.get(key, '')
+            if value and isinstance(value, str):
+                value = value.replace("\n", "\n   ")
+                ret.append(f':{key}:\n   {value}')
     else:
         for key, val in data.items():
-            if key not in (not_these or ['title', 'description', 'URL']):
+            if (
+                key not in (not_these or ['title', 'description', 'URL'])
+                and isinstance(val, str)
+            ):
                 value = val.replace("\n", "\n   ")
                 ret.append(f':{key}:\n   {value}')
     return ret
diff --git a/etc/flow/global.cylc b/etc/flow/global.cylc
index cd28297..5f26b6f 100644
--- a/etc/flow/global.cylc
+++ b/etc/flow/global.cylc
@@ -32,6 +32,7 @@
     [[camden_town]]
         hosts = northern, buslink
         job runner = pbs
+        install target = northern
 [platform groups]
     [[northern line]]
         platforms = camden_town, mornington_crescent