Skip to content

Commit

Permalink
re
Browse files Browse the repository at this point in the history
  • Loading branch information
wxtim committed Aug 20, 2024
1 parent b123fce commit 3f5fbec
Showing 4 changed files with 103 additions and 27 deletions.
10 changes: 10 additions & 0 deletions cylc/sphinx_ext/cylc_lang/__init__.py
Original file line number Diff line number Diff line change
@@ -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::
106 changes: 82 additions & 24 deletions cylc/sphinx_ext/cylc_lang/autodocumenters.py
Original file line number Diff line number Diff line change
@@ -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
5 changes: 2 additions & 3 deletions etc/flow.cylc
Original file line number Diff line number Diff line change
@@ -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
9 changes: 9 additions & 0 deletions etc/flow/global.cylc
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 3f5fbec

Please sign in to comment.