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