From ba64ea22830dd8e627428d7a0002c4ff70cd408d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= <rverschelde@gmail.com>
Date: Wed, 12 Sep 2018 17:12:23 +0200
Subject: [PATCH 1/2] Doc: Use same headers and order in-editor and online

---
 doc/tools/makerst.py   | 95 +++++++++++++++++++++++++-----------------
 editor/editor_help.cpp | 56 ++++++++++++++-----------
 2 files changed, 89 insertions(+), 62 deletions(-)

diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py
index 93ad823d424..056e5ca57f0 100755
--- a/doc/tools/makerst.py
+++ b/doc/tools/makerst.py
@@ -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')
-    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 and enums
     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:
-        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')
-
+    # Enums
     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)
diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp
index 8d371714cf3..5b9e7b29a9a 100644
--- a/editor/editor_help.cpp
+++ b/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();
 

From a923eff9a498af7780615a7dfaf6031eacf3510f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= <rverschelde@gmail.com>
Date: Thu, 13 Sep 2018 01:55:56 +0200
Subject: [PATCH 2/2] Doc: Use PascalCase names in hyperlinks

We were not consistently applying .lower() every time we construct
an hyperlink, so there would be case mismatch. It works fine to keep
the natural case for those links.
---
 doc/tools/makerst.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py
index 056e5ca57f0..06b842d8e6c 100755
--- a/doc/tools/makerst.py
+++ b/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