From 3c8abbc4bf6d2e7b6706468f6af3eb4b270ab7bf Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 14 Jan 2020 21:38:54 +0100 Subject: [PATCH] doc: Move the class description to be just below the brief description - Drop the "Brief description" header as it became redundant with this change. - Fix a bug in the editor help where an extraneous newline was added after the header if the class isn't inherited by any others. - Remove the Category line in the rST markup as it's not useful for API users. --- doc/tools/makerst.py | 29 ++++----- editor/editor_help.cpp | 132 +++++++++++++++++++---------------------- 2 files changed, 74 insertions(+), 87 deletions(-) diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py index 91240e9550..4b07bf00ee 100755 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -393,15 +393,22 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S f.write(make_type(child, state)) f.write("\n\n") - # Category - if class_def.category is not None: - f.write('**Category:** ' + class_def.category.strip() + "\n\n") - # Brief description - f.write(make_heading('Brief Description', '-')) if class_def.brief_description is not None: f.write(rstize_text(class_def.brief_description.strip(), state) + "\n\n") + # Class description + if class_def.description is not None and class_def.description.strip() != '': + f.write(make_heading('Description', '-')) + f.write(rstize_text(class_def.description.strip(), state) + "\n\n") + + # Online tutorials + if len(class_def.tutorials) > 0: + f.write(make_heading('Tutorials', '-')) + for t in class_def.tutorials: + link = t.strip() + f.write("- " + make_url(link) + "\n\n") + # Properties overview if len(class_def.properties) > 0: f.write(make_heading('Properties', '-')) @@ -494,18 +501,6 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S f.write('\n\n') - # Class description - if class_def.description is not None and class_def.description.strip() != '': - f.write(make_heading('Description', '-')) - f.write(rstize_text(class_def.description.strip(), state) + "\n\n") - - # Online tutorials - if len(class_def.tutorials) > 0: - f.write(make_heading('Tutorials', '-')) - for t in class_def.tutorials: - link = t.strip() - f.write("- " + make_url(link) + "\n\n") - # Property descriptions if any(not p.overridden for p in class_def.properties.values()) > 0: f.write(make_heading('Property Descriptions', '-')) diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp index a0c106441a..53c1d334d2 100644 --- a/editor/editor_help.cpp +++ b/editor/editor_help.cpp @@ -418,10 +418,10 @@ void EditorHelp::_update_doc() { } } - if (found) + if (found) { class_desc->pop(); - - class_desc->add_newline(); + class_desc->add_newline(); + } } class_desc->add_newline(); @@ -430,9 +430,26 @@ void EditorHelp::_update_doc() { // Brief description if (cd.brief_description != "") { + class_desc->push_color(text_color); + class_desc->push_font(doc_bold_font); + class_desc->push_indent(1); + _add_text(cd.brief_description); + class_desc->pop(); + class_desc->pop(); + class_desc->pop(); + class_desc->add_newline(); + class_desc->add_newline(); + class_desc->add_newline(); + } + + // Class description + if (cd.description != "") { + + section_line.push_back(Pair(TTR("Description"), class_desc->get_line_count() - 2)); + description_line = class_desc->get_line_count() - 2; class_desc->push_color(title_color); class_desc->push_font(doc_title_font); - class_desc->add_text(TTR("Brief Description")); + class_desc->add_text(TTR("Description")); class_desc->pop(); class_desc->pop(); @@ -441,7 +458,7 @@ void EditorHelp::_update_doc() { class_desc->push_color(text_color); class_desc->push_font(doc_font); class_desc->push_indent(1); - _add_text(cd.brief_description); + _add_text(cd.description); class_desc->pop(); class_desc->pop(); class_desc->pop(); @@ -450,6 +467,46 @@ void EditorHelp::_update_doc() { class_desc->add_newline(); } + // Online tutorials + { + class_desc->push_color(title_color); + class_desc->push_font(doc_title_font); + class_desc->add_text(TTR("Online Tutorials")); + class_desc->pop(); + class_desc->pop(); + class_desc->push_indent(1); + + class_desc->push_font(doc_code_font); + + class_desc->add_newline(); + // class_desc->add_newline(); + + if (cd.tutorials.size() != 0) { + + for (int i = 0; i < cd.tutorials.size(); i++) { + String link = cd.tutorials[i]; + String linktxt = link; + int seppos = linktxt.find("//"); + if (seppos != -1) { + linktxt = link.right(seppos + 2); + } + + class_desc->push_color(symbol_color); + class_desc->append_bbcode("[url=" + link + "]" + linktxt + "[/url]"); + class_desc->pop(); + class_desc->add_newline(); + } + } else { + class_desc->push_color(comment_color); + class_desc->append_bbcode(TTR("There are currently no tutorials for this class, you can [color=$color][url=$url]contribute one[/url][/color] or [color=$color][url=$url2]request one[/url][/color].").replace("$url2", REQUEST_URL).replace("$url", CONTRIBUTE2_URL).replace("$color", link_color_text)); + class_desc->pop(); + } + class_desc->pop(); + class_desc->pop(); + class_desc->add_newline(); + class_desc->add_newline(); + } + // Properties overview Set skip_methods; bool property_descr = false; @@ -922,71 +979,6 @@ void EditorHelp::_update_doc() { } } - // Class description - if (cd.description != "") { - - section_line.push_back(Pair(TTR("Class Description"), class_desc->get_line_count() - 2)); - description_line = class_desc->get_line_count() - 2; - class_desc->push_color(title_color); - class_desc->push_font(doc_title_font); - class_desc->add_text(TTR("Class Description")); - class_desc->pop(); - class_desc->pop(); - - class_desc->add_newline(); - class_desc->add_newline(); - class_desc->push_color(text_color); - class_desc->push_font(doc_font); - class_desc->push_indent(1); - _add_text(cd.description); - class_desc->pop(); - class_desc->pop(); - class_desc->pop(); - class_desc->add_newline(); - class_desc->add_newline(); - class_desc->add_newline(); - } - - // Online tutorials - { - class_desc->push_color(title_color); - class_desc->push_font(doc_title_font); - class_desc->add_text(TTR("Online Tutorials")); - class_desc->pop(); - class_desc->pop(); - class_desc->push_indent(1); - - class_desc->push_font(doc_code_font); - - class_desc->add_newline(); - // class_desc->add_newline(); - - if (cd.tutorials.size() != 0) { - - for (int i = 0; i < cd.tutorials.size(); i++) { - String link = cd.tutorials[i]; - String linktxt = link; - int seppos = linktxt.find("//"); - if (seppos != -1) { - linktxt = link.right(seppos + 2); - } - - class_desc->push_color(symbol_color); - class_desc->append_bbcode("[url=" + link + "]" + linktxt + "[/url]"); - class_desc->pop(); - class_desc->add_newline(); - } - } else { - class_desc->push_color(comment_color); - class_desc->append_bbcode(TTR("There are currently no tutorials for this class, you can [color=$color][url=$url]contribute one[/url][/color] or [color=$color][url=$url2]request one[/url][/color].").replace("$url2", REQUEST_URL).replace("$url", CONTRIBUTE2_URL).replace("$color", link_color_text)); - class_desc->pop(); - } - class_desc->pop(); - class_desc->pop(); - class_desc->add_newline(); - class_desc->add_newline(); - } - // Property descriptions if (property_descr) {