Merge pull request #22002 from akien-mga/doc-unify-editor-rst
Doc: Use same headers and order in-editor and online
This commit is contained in:
Rémi Verschelde
GitHub
commit
f438d311ae
2 changed files with 91 additions and 64 deletions
|
|
@ -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')
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue