Merge pull request #22002 from akien-mga/doc-unify-editor-rst

Doc: Use same headers and order in-editor and online

doc/tools/makerst.py

@@ -312,7 +312,7 @@ def rstize_text(text, cclass):
 def make_type(t):
     global class_names
     if t in class_names:
-        return ':ref:`' + t + '<class_' + t.lower() + '>`'
+        return ':ref:`' + t + '<class_' + t + '>`'
     return t
 
 
@@ -332,7 +332,7 @@ def make_enum(t):
         c = "@GlobalScope"
         e = t
     if c in class_names:
-        return ':ref:`' + e + '<enum_' + c.lower() + '_' + e.lower() + '>`'
+        return ':ref:`' + e + '<enum_' + c + '_' + e + '>`'
     return t
 
 
@@ -435,6 +435,8 @@ def make_rst_class(node):
     f.write(".. _class_" + name + ":\n\n")
     f.write(make_heading(name, '='))
 
+    # Inheritance tree
+    # Ascendents
     if 'inherits' in node.attrib:
         inh = node.attrib['inherits'].strip()
         f.write('**Inherits:** ')
@@ -451,35 +453,40 @@ def make_rst_class(node):
                 inh = inode.attrib['inherits'].strip()
             else:
                 inh = None
+        f.write("\n")
 
-        f.write("\n\n")
+    # Descendents
-
     inherited = []
     for cn in classes:
         c = classes[cn]
         if 'inherits' in c.attrib:
             if (c.attrib['inherits'].strip() == name):
                 inherited.append(c.attrib['name'])
-
     if (len(inherited)):
         f.write('**Inherited By:** ')
         for i in range(len(inherited)):
             if (i > 0):
                 f.write(", ")
             f.write(make_type(inherited[i]))
-        f.write("\n\n")
+        f.write("\n")
+
+    # Category
     if 'category' in node.attrib:
         f.write('**Category:** ' + node.attrib['category'].strip() + "\n\n")
 
+    # Brief description
     f.write(make_heading('Brief Description', '-'))
     briefd = node.find('brief_description')
     if briefd != None:
         f.write(rstize_text(briefd.text.strip(), name) + "\n\n")
 
-    methods = node.find('methods')
+    # Properties overview
+    # TODO: Implement
 
+    # Methods overview
+    methods = node.find('methods')
     if methods != None and len(list(methods)) > 0:
-        f.write(make_heading('Member Functions', '-'))
+        f.write(make_heading('Methods', '-'))
         ml = []
         for m in list(methods):
             make_method(f, node.attrib['name'], m, False, name, False, ml)
@@ -512,6 +519,10 @@ def make_rst_class(node):
             f.write(sep)
         f.write('\n')
 
+    # Theme properties
+    # TODO: Implement
+
+    # Signals
     events = node.find('signals')
     if events != None and len(list(events)) > 0:
         f.write(make_heading('Signals', '-'))
@@ -527,24 +538,7 @@ def make_rst_class(node):
 
         f.write('\n')
 
-    members = node.find('members')
+    # Constants and enums
-    if members != None and len(list(members)) > 0:
-        f.write(make_heading('Member Variables', '-'))
-
-        for c in list(members):
-            # Leading two spaces necessary to prevent breaking the <ul>
-            f.write("  .. _class_" + name + "_" + c.attrib['name'] + ":\n\n")
-            s = '- '
-            if 'enum' in c.attrib:
-                s += make_enum(c.attrib['enum']) + ' '
-            else:
-                s += make_type(c.attrib['type']) + ' '
-            s += '**' + c.attrib['name'] + '**'
-            if c.text.strip() != '':
-                s += ' - ' + rstize_text(c.text.strip(), name)
-            f.write(s + '\n\n')
-        f.write('\n')
-
     constants = node.find('constants')
     consts = []
     enum_names = set()
@@ -557,20 +551,9 @@ def make_rst_class(node):
             else:
                 consts.append(c)
 
-    if len(consts) > 0:
+    # Enums
-        f.write(make_heading('Numeric Constants', '-'))
-        for c in list(consts):
-            s = '- '
-            s += '**' + c.attrib['name'] + '**'
-            if 'value' in c.attrib:
-                s += ' = **' + c.attrib['value'] + '**'
-            if c.text.strip() != '':
-                s += ' --- ' + rstize_text(c.text.strip(), name)
-            f.write(s + '\n')
-        f.write('\n')
-
     if len(enum_names) > 0:
-        f.write(make_heading('Enums', '-'))
+        f.write(make_heading('Enumerations', '-'))
         for e in enum_names:
             f.write("  .. _enum_" + name + "_" + e + ":\n\n")
             f.write("enum **" + e + "**\n\n")
@@ -587,11 +570,26 @@ def make_rst_class(node):
             f.write('\n')
         f.write('\n')
 
+    # Constants
+    if len(consts) > 0:
+        f.write(make_heading('Constants', '-'))
+        for c in list(consts):
+            s = '- '
+            s += '**' + c.attrib['name'] + '**'
+            if 'value' in c.attrib:
+                s += ' = **' + c.attrib['value'] + '**'
+            if c.text.strip() != '':
+                s += ' --- ' + rstize_text(c.text.strip(), name)
+            f.write(s + '\n')
+        f.write('\n')
+
+    # Class description
     descr = node.find('description')
     if descr != None and descr.text.strip() != '':
         f.write(make_heading('Description', '-'))
         f.write(rstize_text(descr.text.strip(), name) + "\n\n")
 
+    # Online tutorials
     global godot_docs_pattern
     tutorials = node.find('tutorials')
     if tutorials != None and len(tutorials) > 0:
@@ -618,9 +616,30 @@ def make_rst_class(node):
                 f.write("- `" + link + " <" + link + ">`_\n")
         f.write("\n")
 
+    # Property descriptions
+    # TODO: Add setter and getter like in-editor help
+    members = node.find('members')
+    if members != None and len(list(members)) > 0:
+        f.write(make_heading('Property Descriptions', '-'))
+
+        for c in list(members):
+            # Leading two spaces necessary to prevent breaking the <ul>
+            f.write("  .. _class_" + name + "_" + c.attrib['name'] + ":\n\n")
+            s = '- '
+            if 'enum' in c.attrib:
+                s += make_enum(c.attrib['enum']) + ' '
+            else:
+                s += make_type(c.attrib['type']) + ' '
+            s += '**' + c.attrib['name'] + '**'
+            if c.text.strip() != '':
+                s += ' - ' + rstize_text(c.text.strip(), name)
+            f.write(s + '\n\n')
+        f.write('\n')
+
+    # Method descriptions
     methods = node.find('methods')
     if methods != None and len(list(methods)) > 0:
-        f.write(make_heading('Member Function Description', '-'))
+        f.write(make_heading('Method Descriptions', '-'))
         for m in list(methods):
             f.write(".. _class_" + name + "_" + m.attrib['name'] + ":\n\n")
             make_method(f, node.attrib['name'], m, True, name)

editor/editor_help.cpp

@@ -776,6 +776,7 @@ void EditorHelp::_update_doc() {
 	Ref<Font> doc_code_font = get_font("doc_source", "EditorFonts");
 	String link_color_text = title_color.to_html(false);
 
+	// Class name
 	section_line.push_back(Pair<String, int>(TTR("Top"), 0));
 	class_desc->push_font(doc_title_font);
 	class_desc->push_color(title_color);
@@ -787,18 +788,18 @@ void EditorHelp::_update_doc() {
 	class_desc->pop();
 	class_desc->add_newline();
 
+	// Inheritance tree
+
+	// Ascendents
 	if (cd.inherits != "") {
 
 		class_desc->push_color(title_color);
-		class_desc->push_font(doc_title_font);
+		class_desc->push_font(doc_font);
 		class_desc->add_text(TTR("Inherits:") + " ");
 		class_desc->pop();
-		class_desc->pop();
 
 		String inherits = cd.inherits;
 
-		class_desc->push_font(doc_font);
-
 		while (inherits != "") {
 			_add_type(inherits);
 
@@ -813,6 +814,7 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	// Descendents
 	if (ClassDB::class_exists(cd.name)) {
 
 		bool found = false;
@@ -824,13 +826,10 @@ void EditorHelp::_update_doc() {
 
 				if (!found) {
 					class_desc->push_color(title_color);
-					class_desc->push_font(doc_title_font);
+					class_desc->push_font(doc_font);
 					class_desc->add_text(TTR("Inherited by:") + " ");
 					class_desc->pop();
-					class_desc->pop();
-
 					found = true;
-					class_desc->push_font(doc_font);
 				}
 
 				if (prev) {
@@ -853,6 +852,7 @@ void EditorHelp::_update_doc() {
 	class_desc->add_newline();
 	class_desc->add_newline();
 
+	// Brief description
 	if (cd.brief_description != "") {
 
 		class_desc->push_color(title_color);
@@ -874,15 +874,16 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	// Properties overview
 	Set<String> skip_methods;
 	bool property_descr = false;
 
 	if (cd.properties.size()) {
 
-		section_line.push_back(Pair<String, int>(TTR("Members"), class_desc->get_line_count() - 2));
+		section_line.push_back(Pair<String, int>(TTR("Properties"), class_desc->get_line_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
-		class_desc->add_text(TTR("Members:"));
+		class_desc->add_text(TTR("Properties:"));
 		class_desc->pop();
 		class_desc->pop();
 
@@ -940,6 +941,7 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	// Methods overview
 	bool method_descr = false;
 	bool sort_methods = EditorSettings::get_singleton()->get("text_editor/help/sort_functions_alphabetically");
 
@@ -956,10 +958,10 @@ void EditorHelp::_update_doc() {
 		if (sort_methods)
 			methods.sort();
 
-		section_line.push_back(Pair<String, int>(TTR("Public Methods"), class_desc->get_line_count() - 2));
+		section_line.push_back(Pair<String, int>(TTR("Methods"), class_desc->get_line_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
-		class_desc->add_text(TTR("Public Methods:"));
+		class_desc->add_text(TTR("Methods:"));
 		class_desc->pop();
 		class_desc->pop();
 
@@ -1024,22 +1026,20 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	// Theme properties
 	if (cd.theme_properties.size()) {
 
-		section_line.push_back(Pair<String, int>(TTR("GUI Theme Items"), class_desc->get_line_count() - 2));
+		section_line.push_back(Pair<String, int>(TTR("Theme Properties"), class_desc->get_line_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
-		class_desc->add_text(TTR("GUI Theme Items:"));
+		class_desc->add_text(TTR("Theme Properties:"));
 		class_desc->pop();
 		class_desc->pop();
-		// class_desc->add_newline();
 
 		class_desc->push_indent(1);
 		class_desc->push_table(2);
 		class_desc->set_table_column_expand(1, 1);
 
-		//class_desc->add_newline();
-
 		for (int i = 0; i < cd.theme_properties.size(); i++) {
 
 			theme_property_line[cd.theme_properties[i].name] = class_desc->get_line_count() - 2; //gets overridden if description
@@ -1076,6 +1076,7 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	// Signals
 	if (cd.signals.size()) {
 
 		if (sort_methods) {
@@ -1144,6 +1145,7 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	// Constants and enums
 	if (cd.constants.size()) {
 
 		Map<String, Vector<DocData::ConstantDoc> > enums;
@@ -1163,6 +1165,7 @@ void EditorHelp::_update_doc() {
 			}
 		}
 
+		// Enums
 		if (enums.size()) {
 
 			section_line.push_back(Pair<String, int>(TTR("Enumerations"), class_desc->get_line_count() - 2));
@@ -1245,6 +1248,7 @@ void EditorHelp::_update_doc() {
 			class_desc->add_newline();
 		}
 
+		// Constants
 		if (constants.size()) {
 
 			section_line.push_back(Pair<String, int>(TTR("Constants"), class_desc->get_line_count() - 2));
@@ -1303,13 +1307,14 @@ void EditorHelp::_update_doc() {
 		}
 	}
 
+	// Class description
 	if (cd.description != "") {
 
-		section_line.push_back(Pair<String, int>(TTR("Description"), class_desc->get_line_count() - 2));
+		section_line.push_back(Pair<String, int>(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("Description:"));
+		class_desc->add_text(TTR("Class Description:"));
 		class_desc->pop();
 		class_desc->pop();
 
@@ -1326,8 +1331,8 @@ 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:"));
@@ -1365,12 +1370,14 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 		class_desc->add_newline();
 	}
+
+	// Property descriptions
 	if (property_descr) {
 
-		section_line.push_back(Pair<String, int>(TTR("Properties"), class_desc->get_line_count() - 2));
+		section_line.push_back(Pair<String, int>(TTR("Property Descriptions"), class_desc->get_line_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
-		class_desc->add_text(TTR("Property Description:"));
+		class_desc->add_text(TTR("Property Descriptions:"));
 		class_desc->pop();
 		class_desc->pop();
 
@@ -1458,12 +1465,13 @@ void EditorHelp::_update_doc() {
 		}
 	}
 
+	// Method descriptions
 	if (method_descr) {
 
-		section_line.push_back(Pair<String, int>(TTR("Methods"), class_desc->get_line_count() - 2));
+		section_line.push_back(Pair<String, int>(TTR("Method Descriptions"), class_desc->get_line_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
-		class_desc->add_text(TTR("Method Description:"));
+		class_desc->add_text(TTR("Method Descriptions:"));
 		class_desc->pop();
 		class_desc->pop();