gaming/godot
gaming/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot synced 2024-09-04 22:08:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #63203 from YuriSizov/a-gaping-hole-in-my-docs

Browse source 
Add more call-to-action notes when documentation is missing
This commit is contained in:
Rémi Verschelde 2022-11-17 20:58:05 +01:00
parent b41ba331d4 270c810343
commit 7d9923b2e0
No known key found for this signature in database
GPG key ID: C3336907360768E1
3 changed files with 98 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
doc/tools/make_rst.py
View file

@ -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

50
editor/editor_help.cpp
View file

@ -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;
}

2
editor/editor_help.h
View file

@ -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();