def rst_title_and_table(title, table_titles, table_values):
"""Generate table in section with title in .rst format."""
doc = []
if title is not None:
doc.extend([title, "-" * len(title), ""])
doc.extend(mk_rst_table(table_titles, table_values))
return doc
def avail_easyconfig_params_rst(title, grouped_params):
"""
Compose overview of available easyconfig parameters, in RST format.
"""
# main title
lines = [
title,
'=' * len(title),
'',
]
for grpname in grouped_params:
# group section title
lines.append("%s parameters" % grpname)
lines.extend(['-' * len(lines[-1]), ''])
titles = ["**Parameter name**", "**Description**", "**Default value**"]
values = [
['``' + name + '``' for name in grouped_params[grpname].keys()], # parameter name
[x[0] for x in grouped_params[grpname].values()], # description
[str(quote_str(x[1])) for x in grouped_params[grpname].values()] # default value
]
lines.extend(mk_rst_table(titles, values))
lines.append('')
return '\n'.join(lines)
def rst_title_and_table(title, table_titles, table_values):
"""Generate table in section with title in .rst format."""
doc = [
title,
'-' * len(title),
'',
]
doc.extend(mk_rst_table(table_titles, table_values))
return doc
def rst_title_and_table(title, table_titles, table_values):
"""Generate table in section with title in .rst format."""
doc = [
title,
'-' * len(title),
'',
]
doc.extend(mk_rst_table(table_titles, table_values))
return doc
def avail_cfgfile_constants_rst(go_cfg_constants):
title = "Constants available (only) in configuration files"
doc =[title, '-' * len(title), '']
for section in go_cfg_constants:
doc.append('')
if section != go_cfg_constants['DEFAULT']:
section_title = "only in '%s' section:" %section
doc.extend([section_title, '-' * len(section_title), ''])
table_titles = ["Constant name", "Constant help", "Constant value"]
table_values = [
['``' + name + '``' for name in go_cfg_constants[section].keys()],
[tup[1] for tup in go_cfg_constants[section].values()],
['``' + tup[0] + '``' for tup in go_cfg_constants[section].values()],
]
doc.extend(mk_rst_table(table_titles, table_values))
return '\n'.join(doc)
def avail_cfgfile_constants_rst(go_cfg_constants):
title = "Constants available (only) in configuration files"
doc =[title, '-' * len(title), '']
for section in go_cfg_constants:
doc.append('')
if section != go_cfg_constants['DEFAULT']:
section_title = "only in '%s' section:" %section
doc.extend([section_title, '-' * len(section_title), ''])
table_titles = ["Constant name", "Constant help", "Constant value"]
table_values = [
['``' + name + '``' for name in go_cfg_constants[section].keys()],
[tup[1] for tup in go_cfg_constants[section].values()],
['``' + tup[0] + '``' for tup in go_cfg_constants[section].values()],
]
doc.extend(mk_rst_table(table_titles, table_values))
return '\n'.join(doc)
def avail_cfgfile_constants_rst(go_cfg_constants):
title = "Constants available (only) in configuration files"
doc = [title, "-" * len(title), ""]
for section in go_cfg_constants:
doc.append("")
if section != go_cfg_constants["DEFAULT"]:
section_title = "only in '%s' section:" % section
doc.extend([section_title, "-" * len(section_title), ""])
table_titles = ["Constant name", "Constant help", "Constant value"]
table_values = [
["``" + name + "``" for name in go_cfg_constants[section].keys()],
[tup[1] for tup in go_cfg_constants[section].values()],
["``" + tup[0] + "``" for tup in go_cfg_constants[section].values()],
]
doc.extend(mk_rst_table(table_titles, table_values))
return "\n".join(doc)
def test_mk_rst_table(self):
"""Test mk_rst_table function."""
entries = [['one', 'two', 'three']]
t = 'This title is longer than the entries in the column'
titles = [t]
# small table
table = mk_rst_table(titles, entries)
check = [
'=' * len(t),
t,
'=' * len(t),
'one' + ' ' * (len(t) - 3),
'two' + ' ' * (len(t) - 3),
'three' + ' ' * (len(t) - 5),
'=' * len(t),
'',
]
self.assertEqual(table, check)
def test_mk_rst_table(self):
"""Test mk_rst_table function."""
entries = [['one', 'two', 'three']]
t = 'This title is longer than the entries in the column'
titles = [t]
# small table
table = mk_rst_table(titles, entries)
check = [
'=' * len(t),
t,
'=' * len(t),
'one' + ' ' * (len(t) - 3),
'two' + ' ' * (len(t) -3),
'three' + ' ' * (len(t) - 5),
'=' * len(t),
'',
]
self.assertEqual(table, check)
def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks):
"""
Compose overview of one easyblock given class object of the easyblock in rst format
"""
classname = eb_class.__name__
lines = [
'.. _' + classname + ':',
'',
'``' + classname + '``',
'=' * (len(classname)+4),
'',
]
bases = []
for b in eb_class.__bases__:
base = ':ref:`' + b.__name__ +'`' if b in all_blocks else b.__name__
bases.append(base)
derived = '(derives from ' + ', '.join(bases) + ')'
lines.extend([derived, ''])
# Description (docstring)
lines.extend([eb_class.__doc__.strip(), ''])
# Add extra options, if any
if eb_class.extra_options():
extra_parameters = 'Extra easyconfig parameters specific to ``' + classname + '`` easyblock'
lines.extend([extra_parameters, '-' * len(extra_parameters), ''])
ex_opt = eb_class.extra_options()
titles = ['easyconfig parameter', 'description', 'default value']
values = [
['``' + key + '``' for key in ex_opt], # parameter name
[val[1] for val in ex_opt.values()], # description
['``' + str(quote_str(val[0])) + '``' for val in ex_opt.values()] # default value
]
lines.extend(mk_rst_table(titles, values))
# Add commonly used parameters
if classname in common_params:
commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock'
lines.extend([commonly_used, '-' * len(commonly_used)])
titles = ['easyconfig parameter', 'description']
values = [
[opt for opt in common_params[classname]],
[DEFAULT_CONFIG[opt][1] for opt in common_params[classname]],
]
lines.extend(mk_rst_table(titles, values))
lines.append('')
# Add docstring for custom steps
custom = []
inh = ''
f = None
for func in doc_functions:
if func in eb_class.__dict__:
f = eb_class.__dict__[func]
if f.__doc__:
custom.append('* ``' + func + '`` - ' + f.__doc__.strip() + inh)
if custom:
title = 'Customised steps in ``' + classname + '`` easyblock'
lines.extend([title, '-' * len(title)] + custom)
lines.append('')
# Add example if available
if os.path.exists(os.path.join(path_to_examples, '%s.eb' % classname)):
title = 'Example for ``' + classname + '`` easyblock'
lines.extend(['', title, '-' * len(title), '', '::', ''])
for line in read_file(os.path.join(path_to_examples, classname+'.eb')).split('\n'):
lines.append(' ' + line.strip())
lines.append('') # empty line after literal block
return '\n'.join(lines)
