diff options
Diffstat (limited to 'doc/tools/makerst.py')
| -rwxr-xr-x | doc/tools/makerst.py | 78 |
1 files changed, 57 insertions, 21 deletions
diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py index b42ae3ce01..ef38299680 100755 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -37,13 +37,14 @@ class TypeName: class PropertyDef: - def __init__(self, name, type_name, setter, getter, text, default_value): # type: (str, TypeName, Optional[str], Optional[str], Optional[str], Optional[str]) -> None + def __init__(self, name, type_name, setter, getter, text, default_value, overridden): # type: (str, TypeName, Optional[str], Optional[str], Optional[str], Optional[str], Optional[bool]) -> None self.name = name self.type_name = type_name self.setter = setter self.getter = getter self.text = text self.default_value = default_value + self.overridden = overridden class ParameterDef: def __init__(self, name, type_name, default_value): # type: (str, TypeName, Optional[str]) -> None @@ -147,8 +148,9 @@ class State: setter = property.get("setter") or None # Use or None so '' gets turned into None. getter = property.get("getter") or None default_value = property.get("default") or None + overridden = property.get("override") or False - property_def = PropertyDef(property_name, type_name, setter, getter, property.text, default_value) + property_def = PropertyDef(property_name, type_name, setter, getter, property.text, default_value, overridden) class_def.properties[property_name] = property_def methods = class_root.find("methods") @@ -401,12 +403,15 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Properties overview if len(class_def.properties) > 0: f.write(make_heading('Properties', '-')) - ml = [] # type: List[Tuple[str, str]] + ml = [] # type: List[Tuple[str, str, str]] for property_def in class_def.properties.values(): type_rst = property_def.type_name.to_rst(state) - ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name) default = property_def.default_value - ml.append((type_rst, ref, default)) + if property_def.overridden: + ml.append((type_rst, property_def.name, "**O:** " + default)) + else: + ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name) + ml.append((type_rst, ref, default)) format_table(f, ml, True) # Methods overview @@ -430,21 +435,30 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Signals if len(class_def.signals) > 0: f.write(make_heading('Signals', '-')) + index = 0 + for signal in class_def.signals.values(): - #f.write(".. _class_{}_{}:\n\n".format(class_name, signal.name)) + if index != 0: + f.write('----\n\n') + f.write(".. _class_{}_signal_{}:\n\n".format(class_name, signal.name)) _, signature = make_method_signature(class_def, signal, False, state) f.write("- {}\n\n".format(signature)) - if signal.description is None or signal.description.strip() == '': - continue - f.write(rstize_text(signal.description.strip(), state)) - f.write("\n\n") + if signal.description is not None and signal.description.strip() != '': + f.write(rstize_text(signal.description.strip(), state) + '\n\n') + + index += 1 # Enums if len(class_def.enums) > 0: f.write(make_heading('Enumerations', '-')) + index = 0 + for e in class_def.enums.values(): + if index != 0: + f.write('----\n\n') + f.write(".. _enum_{}_{}:\n\n".format(class_name, e.name)) # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. @@ -458,8 +472,11 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S f.write("- **{}** = **{}**".format(value.name, value.value)) if value.text is not None and value.text.strip() != '': f.write(' --- ' + rstize_text(value.text.strip(), state)) + f.write('\n\n') + index += 1 + # Constants if len(class_def.constants) > 0: f.write(make_heading('Constants', '-')) @@ -472,6 +489,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S f.write("- **{}** = **{}**".format(constant.name, constant.value)) if constant.text is not None and constant.text.strip() != '': f.write(' --- ' + rstize_text(constant.text.strip(), state)) + f.write('\n\n') # Class description @@ -487,10 +505,17 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S f.write("- " + make_url(link) + "\n\n") # Property descriptions - if len(class_def.properties) > 0: + if any(not p.overridden for p in class_def.properties.values()) > 0: f.write(make_heading('Property Descriptions', '-')) + index = 0 + for property_def in class_def.properties.values(): - #f.write(".. _class_{}_{}:\n\n".format(class_name, property_def.name)) + if property_def.overridden: + continue + + if index != 0: + f.write('----\n\n') + f.write(".. _class_{}_property_{}:\n\n".format(class_name, property_def.name)) f.write('- {} **{}**\n\n'.format(property_def.type_name.to_rst(state), property_def.name)) @@ -506,24 +531,30 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S format_table(f, info) if property_def.text is not None and property_def.text.strip() != '': - f.write(rstize_text(property_def.text.strip(), state)) - f.write('\n\n') + f.write(rstize_text(property_def.text.strip(), state) + '\n\n') + + index += 1 # Method descriptions if len(class_def.methods) > 0: f.write(make_heading('Method Descriptions', '-')) + index = 0 + for method_list in class_def.methods.values(): for i, m in enumerate(method_list): + if index != 0: + f.write('----\n\n') + if i == 0: - #f.write(".. _class_{}_{}:\n\n".format(class_name, m.name)) f.write(".. _class_{}_method_{}:\n\n".format(class_name, m.name)) + ret_type, signature = make_method_signature(class_def, m, False, state) f.write("- {} {}\n\n".format(ret_type, signature)) - if m.description is None or m.description.strip() == '': - continue - f.write(rstize_text(m.description.strip(), state)) - f.write("\n\n") + if m.description is not None and m.description.strip() != '': + f.write(rstize_text(m.description.strip(), state) + '\n\n') + + index += 1 def make_class_list(class_list, columns): # type: (List[str], int) -> None @@ -600,8 +631,10 @@ def rstize_text(text, state): # type: (str, State) -> str break pre_text = text[:pos] + indent_level = 0 while text[pos + 1] == '\t': pos += 1 + indent_level += 1 post_text = text[pos + 1:] # Handle codeblocks @@ -625,6 +658,9 @@ def rstize_text(text, state): # type: (str, State) -> str while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == '\t': to_skip += 1 + if to_skip > indent_level: + print_error("Four spaces should be used for indentation within [codeblock], file: {}".format(state.current_class), state) + if len(code_text[code_pos + to_skip + 1:]) == 0: code_text = code_text[:code_pos] + "\n" code_pos += 1 @@ -884,7 +920,7 @@ def rstize_text(text, state): # type: (str, State) -> str def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterable[Tuple[str, ...]]) -> None if len(data) == 0: return - + column_sizes = [0] * len(data[0]) for row in data: for i, text in enumerate(row): @@ -899,7 +935,7 @@ def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterabl sep += "+" + "-" * (size + 2) sep += "+\n" f.write(sep) - + for row in data: row_text = "|" for i, text in enumerate(row): |