def render_fnt(parent_class, f_name, f_overloads):
"""
Generate the rst page for a function
* f_name : name of the function
* overload_docs : ??
* parent_class : None or the parent class if it is a method
* f_overloads : a list of WHAT ?
"""
# Start of the page
R = rst_start
# tag and name of the class
parent_cls_name_fully_qualified = (CL.fully_qualified_name(parent_class) +
"::") if parent_class else ""
parent_cls_spelling = (parent_class.spelling + '_') if parent_class else ''
f_name_full = parent_cls_name_fully_qualified + f_name
R += """
.. _{class_rst_ref}:
{f_name_full}
""".format(f_name_full=f_name_full, class_rst_ref=parent_cls_spelling + f_name)
R += '=' * (len(f_name_full) + 0) + '\n' + """
"""
# Synopsis
R += make_synopsis_list(f_overloads) + '\n\n'
# HOW DO WE GROUP THE OVERLOAD
# Enumerate all overloads
for n, f in enumerate(f_overloads):
doc = f.processed_doc
doc_elem = doc.elements
num = '%s.' % (n + 1) if len(f_overloads) > 1 else ''
R += '\n' + num + ' ' + doc.brief_doc + '\n'
R += doc.doc
# TODO which order ?
if 'note' in doc_elem: R += render_note(doc_elem.pop('note'))
if 'warning' in doc_elem: R += render_warning(doc_elem.pop('warning'))
if 'figure' in doc_elem: R += render_fig(doc_elem.pop('figure'))
if 'tparam' in doc_elem:
R += render_list(doc_elem.pop('tparam'), 'Template parameters')
if 'param' in doc_elem:
R += render_list(doc_elem.pop('param'), 'Parameters')
if 'return' in doc_elem:
R += make_header('Return value') + doc_elem.pop('return')
# any example from the overloads
# Should we TAKE ONLY ONE ????? Error ??
example_file_name = reduce(
lambda x, y: x or y,
[f.processed_doc.elements.pop('example', '') for f in f_overloads], '')
R += render_example(example_file_name)
return R
def render_fnt(f_name, doc_methods, parent_class, f_overloads):
R = rst_start
R += """
.. _{class_rst_ref}:
{f_name}
""".format(
f_name=f_name,
class_rst_ref=((parent_class.spelling + '_') if parent_class else '') +
f_name)
R += '=' * (len(f_name) + 0) + '\n' + """
**Synopsis**:
.. code-block:: c
"""
# Synopsis
R += make_synopsis_list(f_overloads, doc_methods) + '\n\n'
# Enumerate all overloads
for n, (m, doc) in enumerate(zip(f_overloads, doc_methods)):
doc_elem = doc.elements
num = '(%s)' % (n + 1) if len(f_overloads) > 1 else ''
R += num + doc.brief_doc + '\n'
R += replace_latex(render_note('note', doc_elem))
R += replace_latex(render_note('warning', doc_elem))
R += render_fig(doc_elem)
R += render_list(doc_elem['tparam'], 'Template parameters')
R += render_list(doc_elem['param'], 'Parameters')
if doc_elem['return']: R += head('Return value') + doc_elem['return']
if doc.processed_doc:
R += head('Documentation') + replace_latex(doc.processed_doc)
R += '\n\n'
# any example from the overloads
example_file_name = reduce(lambda x, y: x or y,
[d.elements['example']
for d in doc_methods] + [f_name], '')
code, d1, d2, s, e = prepare_example(example_file_name, 4)
if code:
R += """
Example
---------
{d1}
.. triqs_example::
linenos:{s},{e}
{code}
{d2}
""".format(**locals())
return R
def render_fnt(parent_class, f_name, f_overloads):
"""
Generate the rst page for a function
* f_name : name of the function
* overload_docs : ??
* parent_class : None or the parent class if it is a method
* f_overloads : a list of WHAT ?
"""
# Start of the page
R = rst_start
# tag and name of the class
parent_cls_name_fully_qualified = (CL.fully_qualified_name(parent_class) +
"::") if parent_class else ""
parent_cls_name = (parent_class.name + '_') if parent_class else ''
f_name_full = parent_cls_name_fully_qualified + f_name
R += """
.. _{class_rst_ref}:
{f_name_full}
""".format(f_name_full=f_name_full,
class_rst_ref=make_label(parent_cls_name + f_name))
R += '=' * (len(f_name_full) + 0) + '\n' + """
"""
# Synopsis
R += make_synopsis_list(f_overloads) + '\n\n'
# We regroup the overload as in cppreference
def make_unique(topic):
rets = set(
f.processed_doc.elements.pop(topic, '').strip()
for f in f_overloads)
rets = list(x for x in rets if x)
if len(rets) > 1:
print "Warning : Multiple documentation of %s across overloads. Picking first one" % topic
return rets[0] if rets else ''
def make_unique_list(topic):
D = OrderedDict()
for n, f in enumerate(f_overloads):
plist = f.processed_doc.elements.pop(
topic) # p is a string "NAME REST"
for p in plist:
name, desc = (p + ' ').split(' ', 1)
if name not in D:
D[name] = desc.strip()
else:
if D[name] != desc.strip():
print "Warning : multiple definition of parameter %s at overload %s" % (
name, n)
return D
def render_dict(d, header, char):
"""
Make rst code for a list of items with a header
It splits the first word in a separate column
"""
if not d: return ''
head = make_header(header, char) if header else ''
return head + '\n'.join(" * **%s**: %s\n" % (k.strip(), v)
for (k, v) in d.items())
has_overload = len(f_overloads) > 1
# Head doc
head = make_unique('head') or ("Documentation" if has_overload else '')
R += '%s\n\n' % head
# The piece of doc which is overload dependent
for num, f in enumerate(f_overloads):
pd = f.processed_doc
num_s = '**%s)** ' % (num + 1) if has_overload else ''
if pd.doc: R += '\n\n %s %s\n ' % (num_s, pd.doc) + '\n'
# Tail doc
R += '%s\n\n' % make_unique('tail')
# tparam and param
tparam_dict = make_unique_list('tparam')
param_dict = make_unique_list('param')
R += render_dict(tparam_dict, 'Template parameters', '^')
R += render_dict(param_dict, 'Parameters', '^')
# Returns
rets = make_unique("return")
if rets: R += make_header('Returns', '^') + " * %s" % rets
# Examples
example_file_name = make_unique("example")
R += render_example(example_file_name.strip())
# Warning
w = make_unique("warning")
R += render_warning(w)
return R
def render_fnt(parent_class, f_name, f_overloads):
"""
Generate the rst page for a function
* f_name : name of the function
* overload_docs : ??
* parent_class : None or the parent class if it is a method
* f_overloads : a list of WHAT ?
"""
# Start of the page
R = rst_start
# tag and name of the class
parent_cls_name_fully_qualified = (CL.fully_qualified_name(parent_class) + "::") if parent_class else ""
parent_cls_name = (parent_class.name + '_') if parent_class else ''
f_name_full = parent_cls_name_fully_qualified + f_name
R += """
.. _{class_rst_ref}:
{f_name_full}
""".format(f_name_full = f_name_full, class_rst_ref = make_label(parent_cls_name + f_name))
R += '=' * (len(f_name_full)+0) + '\n' + """
"""
# Synopsis
R += make_synopsis_list(f_overloads) + '\n\n'
# We regroup the overload as in cppreference
def make_unique(topic) :
rets = set(f.processed_doc.elements.pop(topic, '').strip() for f in f_overloads)
rets = list(x for x in rets if x)
if len(rets)> 1: print "Warning : Multiple documentation of %s across overloads. Picking first one"%topic
return rets[0] if rets else ''
def make_unique_list(topic) :
D = OrderedDict()
for n, f in enumerate(f_overloads):
plist = f.processed_doc.elements.pop(topic) # p is a string "NAME REST"
for p in plist :
name, desc = (p + ' ').split(' ',1)
if name not in D:
D[name] = desc.strip()
else:
if D[name] != desc.strip() :
print "Warning : multiple definition of parameter %s at overload %s"%(name, n)
return D
def render_dict(d, header, char):
"""
Make rst code for a list of items with a header
It splits the first word in a separate column
"""
if not d: return ''
head = make_header(header, char) if header else ''
return head + '\n'.join(" * **%s**: %s\n"%(k.strip(),v) for (k,v) in d.items())
has_overload = len(f_overloads)> 1
# Head doc
head = make_unique('head') or ("Documentation" if has_overload else '')
R += '%s\n\n'%head
# The piece of doc which is overload dependent
for num, f in enumerate(f_overloads):
pd = f.processed_doc
num_s = '**%s)** '%(num+1) if has_overload else ''
if pd.doc : R += '\n\n %s %s\n '%(num_s, pd.doc)+ '\n'
# Tail doc
R += '%s\n\n' %make_unique('tail')
# tparam and param
tparam_dict = make_unique_list('tparam')
param_dict = make_unique_list('param')
R += render_dict(tparam_dict, 'Template parameters', '^')
R += render_dict(param_dict, 'Parameters','^')
# Returns
rets = make_unique("return")
if rets : R += make_header('Returns', '^') + " * %s"%rets
# Examples
example_file_name = make_unique("example")
R += render_example(example_file_name.strip())
# Warning
w = make_unique("warning")
R += render_warning(w)
return R