Merge pull request #63203 from YuriSizov/a-gaping-hole-in-my-docs
Add more call-to-action notes when documentation is missing
This commit is contained in:
Rémi Verschelde
commit
7d9923b2e0
|
|
@ -723,15 +723,30 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
f.write(make_type(child, state))
|
||||
f.write("\n\n")
|
||||
|
||||
has_description = False
|
||||
|
||||
# Brief description
|
||||
if class_def.brief_description is not None:
|
||||
if class_def.brief_description is not None and class_def.brief_description.strip() != "":
|
||||
has_description = True
|
||||
|
||||
f.write(f"{format_text_block(class_def.brief_description.strip(), class_def, state)}\n\n")
|
||||
|
||||
# Class description
|
||||
if class_def.description is not None and class_def.description.strip() != "":
|
||||
has_description = True
|
||||
|
||||
f.write(make_heading("Description", "-"))
|
||||
f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n")
|
||||
|
||||
if not has_description:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
# Online tutorials
|
||||
if len(class_def.tutorials) > 0:
|
||||
f.write(make_heading("Tutorials", "-"))
|
||||
|
|
@ -872,6 +887,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
|
||||
if m.description is not None and m.description.strip() != "":
|
||||
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
|
||||
else:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this annotation. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
index += 1
|
||||
|
||||
|
|
@ -904,6 +927,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
|
||||
if property_def.text is not None and property_def.text.strip() != "":
|
||||
f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n")
|
||||
else:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
index += 1
|
||||
|
||||
|
|
@ -925,6 +956,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
|
||||
if m.description is not None and m.description.strip() != "":
|
||||
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
|
||||
else:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this constructor. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
index += 1
|
||||
|
||||
|
|
@ -945,6 +984,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
|
||||
if m.description is not None and m.description.strip() != "":
|
||||
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
|
||||
else:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
index += 1
|
||||
|
||||
|
|
@ -967,6 +1014,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
|
||||
if m.description is not None and m.description.strip() != "":
|
||||
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
|
||||
else:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this operator. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
index += 1
|
||||
|
||||
|
|
@ -992,6 +1047,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
|
|||
|
||||
if theme_item_def.text is not None and theme_item_def.text.strip() != "":
|
||||
f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n")
|
||||
else:
|
||||
f.write(".. container:: contribute\n\n\t")
|
||||
f.write(
|
||||
translate(
|
||||
"There is currently no description for this theme property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
|
||||
)
|
||||
+ "\n\n"
|
||||
)
|
||||
|
||||
index += 1
|
||||
|
||||
|
|
|
|||
|
|
@ -446,7 +446,7 @@ Error EditorHelp::_goto_desc(const String &p_class, int p_vscr) {
|
|||
return OK;
|
||||
}
|
||||
|
||||
void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods, bool &r_method_descrpitons) {
|
||||
void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods) {
|
||||
Ref<Font> font = get_theme_font(SNAME("doc_source"), SNAME("EditorFonts"));
|
||||
class_desc->pop(); // title font size
|
||||
class_desc->pop(); // title font
|
||||
|
|
@ -496,10 +496,6 @@ void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods,
|
|||
class_desc->pop(); //cell
|
||||
}
|
||||
|
||||
if (!m[i].description.strip_edges().is_empty() || m[i].errors_returned.size() > 0) {
|
||||
r_method_descrpitons = true;
|
||||
}
|
||||
|
||||
_add_method(m[i], true);
|
||||
}
|
||||
|
||||
|
|
@ -717,11 +713,15 @@ void EditorHelp::_update_doc() {
|
|||
class_desc->add_newline();
|
||||
}
|
||||
|
||||
bool has_description = false;
|
||||
|
||||
class_desc->add_newline();
|
||||
class_desc->add_newline();
|
||||
|
||||
// Brief description
|
||||
if (!cd.brief_description.strip_edges().is_empty()) {
|
||||
has_description = true;
|
||||
|
||||
class_desc->push_color(text_color);
|
||||
class_desc->push_font(doc_bold_font);
|
||||
class_desc->push_indent(1);
|
||||
|
|
@ -736,6 +736,8 @@ void EditorHelp::_update_doc() {
|
|||
|
||||
// Class description
|
||||
if (!cd.description.strip_edges().is_empty()) {
|
||||
has_description = true;
|
||||
|
||||
section_line.push_back(Pair<String, int>(TTR("Description"), class_desc->get_paragraph_count() - 2));
|
||||
description_line = class_desc->get_paragraph_count() - 2;
|
||||
class_desc->push_color(title_color);
|
||||
|
|
@ -760,6 +762,22 @@ void EditorHelp::_update_doc() {
|
|||
class_desc->add_newline();
|
||||
}
|
||||
|
||||
if (!has_description) {
|
||||
class_desc->add_image(get_theme_icon(SNAME("Error"), SNAME("EditorIcons")));
|
||||
class_desc->add_text(" ");
|
||||
class_desc->push_color(comment_color);
|
||||
|
||||
if (cd.is_script_doc) {
|
||||
class_desc->append_text(TTR("There is currently no description for this class."));
|
||||
} else {
|
||||
class_desc->append_text(TTR("There is currently no description for this class. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
|
||||
}
|
||||
|
||||
class_desc->pop();
|
||||
class_desc->add_newline();
|
||||
class_desc->add_newline();
|
||||
}
|
||||
|
||||
// Online tutorials
|
||||
if (cd.tutorials.size()) {
|
||||
class_desc->push_color(title_color);
|
||||
|
|
@ -796,7 +814,6 @@ void EditorHelp::_update_doc() {
|
|||
|
||||
// Properties overview
|
||||
HashSet<String> skip_methods;
|
||||
bool property_descr = false;
|
||||
|
||||
bool has_properties = cd.properties.size() != 0;
|
||||
if (cd.is_script_doc) {
|
||||
|
|
@ -874,7 +891,6 @@ void EditorHelp::_update_doc() {
|
|||
|
||||
if (describe) {
|
||||
class_desc->pop();
|
||||
property_descr = true;
|
||||
}
|
||||
|
||||
class_desc->pop();
|
||||
|
|
@ -959,9 +975,6 @@ void EditorHelp::_update_doc() {
|
|||
}
|
||||
|
||||
// Methods overview
|
||||
bool constructor_descriptions = false;
|
||||
bool method_descriptions = false;
|
||||
bool operator_descriptions = false;
|
||||
bool sort_methods = EDITOR_GET("text_editor/help/sort_functions_alphabetically");
|
||||
|
||||
Vector<DocData::MethodDoc> methods;
|
||||
|
|
@ -989,19 +1002,20 @@ void EditorHelp::_update_doc() {
|
|||
class_desc->push_font(doc_title_font);
|
||||
class_desc->push_font_size(doc_title_font_size);
|
||||
class_desc->add_text(TTR("Constructors"));
|
||||
_update_method_list(cd.constructors, constructor_descriptions);
|
||||
_update_method_list(cd.constructors);
|
||||
}
|
||||
|
||||
if (!methods.is_empty()) {
|
||||
if (sort_methods) {
|
||||
methods.sort();
|
||||
}
|
||||
|
||||
section_line.push_back(Pair<String, int>(TTR("Methods"), class_desc->get_paragraph_count() - 2));
|
||||
class_desc->push_color(title_color);
|
||||
class_desc->push_font(doc_title_font);
|
||||
class_desc->push_font_size(doc_title_font_size);
|
||||
class_desc->add_text(TTR("Methods"));
|
||||
_update_method_list(methods, method_descriptions);
|
||||
_update_method_list(methods);
|
||||
}
|
||||
|
||||
if (!cd.operators.is_empty()) {
|
||||
|
|
@ -1014,7 +1028,7 @@ void EditorHelp::_update_doc() {
|
|||
class_desc->push_font(doc_title_font);
|
||||
class_desc->push_font_size(doc_title_font_size);
|
||||
class_desc->add_text(TTR("Operators"));
|
||||
_update_method_list(cd.operators, operator_descriptions);
|
||||
_update_method_list(cd.operators);
|
||||
}
|
||||
|
||||
// Theme properties
|
||||
|
|
@ -1507,7 +1521,7 @@ void EditorHelp::_update_doc() {
|
|||
}
|
||||
|
||||
// Property descriptions
|
||||
if (property_descr) {
|
||||
if (has_properties) {
|
||||
section_line.push_back(Pair<String, int>(TTR("Property Descriptions"), class_desc->get_paragraph_count() - 2));
|
||||
class_desc->push_color(title_color);
|
||||
class_desc->push_font(doc_title_font);
|
||||
|
|
@ -1682,7 +1696,7 @@ void EditorHelp::_update_doc() {
|
|||
}
|
||||
|
||||
// Constructor descriptions
|
||||
if (constructor_descriptions) {
|
||||
if (!cd.constructors.is_empty()) {
|
||||
section_line.push_back(Pair<String, int>(TTR("Constructor Descriptions"), class_desc->get_paragraph_count() - 2));
|
||||
class_desc->push_color(title_color);
|
||||
class_desc->push_font(doc_title_font);
|
||||
|
|
@ -1692,7 +1706,7 @@ void EditorHelp::_update_doc() {
|
|||
}
|
||||
|
||||
// Method descriptions
|
||||
if (method_descriptions) {
|
||||
if (!methods.is_empty()) {
|
||||
section_line.push_back(Pair<String, int>(TTR("Method Descriptions"), class_desc->get_paragraph_count() - 2));
|
||||
class_desc->push_color(title_color);
|
||||
class_desc->push_font(doc_title_font);
|
||||
|
|
@ -1702,7 +1716,7 @@ void EditorHelp::_update_doc() {
|
|||
}
|
||||
|
||||
// Operator descriptions
|
||||
if (operator_descriptions) {
|
||||
if (!cd.operators.is_empty()) {
|
||||
section_line.push_back(Pair<String, int>(TTR("Operator Descriptions"), class_desc->get_paragraph_count() - 2));
|
||||
class_desc->push_color(title_color);
|
||||
class_desc->push_font(doc_title_font);
|
||||
|
|
@ -1710,6 +1724,8 @@ void EditorHelp::_update_doc() {
|
|||
class_desc->add_text(TTR("Operator Descriptions"));
|
||||
_update_method_descriptions(cd, cd.operators, "operator");
|
||||
}
|
||||
|
||||
// Free the scroll.
|
||||
scroll_locked = false;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -167,7 +167,7 @@ class EditorHelp : public VBoxContainer {
|
|||
|
||||
Error _goto_desc(const String &p_class, int p_vscr = -1);
|
||||
//void _update_history_buttons();
|
||||
void _update_method_list(const Vector<DocData::MethodDoc> p_methods, bool &r_method_descrpitons);
|
||||
void _update_method_list(const Vector<DocData::MethodDoc> p_methods);
|
||||
void _update_method_descriptions(const DocData::ClassDoc p_classdoc, const Vector<DocData::MethodDoc> p_methods, const String &p_method_type);
|
||||
void _update_doc();
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue