Add keywords to the class reference

Allows for finding methods, properties, signals, constants, theme items and annotations more easily. - Allow "keywords" attribute in aforementioned locations in the class reference XMLs - Extends doctool, to preserve these attributes - Update the XSD schema for the class reference - Update the RST generator to include a meta tag for class keywords - Update the editor help to support filtering by keywords
godotengine · Feb 9, 2024 · db798b2 · db798b2
1 parent 94dbf69
commit db798b2
Show file tree

Hide file tree

Showing 6 changed files with 162 additions and 28 deletions.
diff --git a/core/doc_data.h b/core/doc_data.h
@@ -117,6 +117,7 @@ class DocData {
 		bool is_experimental = false;
 		Vector<ArgumentDoc> arguments;
 		Vector<int> errors_returned;
+		String keywords;
 		bool operator<(const MethodDoc &p_method) const {
 			if (name == p_method.name) {
 				// Must be an operator or a constructor since there is no other overloading
@@ -195,6 +196,10 @@ class DocData {
 				doc.errors_returned.push_back(errors_returned[i]);
 			}
 
+			if (p_dict.has("keywords")) {
+				doc.keywords = p_dict["keywords"];
+			}
+
 			return doc;
 		}
 		static Dictionary to_dict(const MethodDoc &p_doc) {
@@ -225,6 +230,10 @@ class DocData {
 
 			dict["is_experimental"] = p_doc.is_experimental;
 
+			if (!p_doc.keywords.is_empty()) {
+				dict["keywords"] = p_doc.keywords;
+			}
+
 			if (!p_doc.arguments.is_empty()) {
 				Array arguments;
 				for (int i = 0; i < p_doc.arguments.size(); i++) {
@@ -254,6 +263,7 @@ class DocData {
 		String description;
 		bool is_deprecated = false;
 		bool is_experimental = false;
+		String keywords;
 		bool operator<(const ConstantDoc &p_const) const {
 			return name < p_const.name;
 		}
@@ -291,6 +301,10 @@ class DocData {
 				doc.is_experimental = p_dict["is_experimental"];
 			}
 
+			if (p_dict.has("keywords")) {
+				doc.keywords = p_dict["keywords"];
+			}
+
 			return doc;
 		}
 		static Dictionary to_dict(const ConstantDoc &p_doc) {
@@ -319,6 +333,10 @@ class DocData {
 
 			dict["is_experimental"] = p_doc.is_experimental;
 
+			if (!p_doc.keywords.is_empty()) {
+				dict["keywords"] = p_doc.keywords;
+			}
+
 			return dict;
 		}
 	};
@@ -335,6 +353,7 @@ class DocData {
 		String overrides;
 		bool is_deprecated = false;
 		bool is_experimental = false;
+		String keywords;
 		bool operator<(const PropertyDoc &p_prop) const {
 			return name.naturalcasecmp_to(p_prop.name) < 0;
 		}
@@ -388,6 +407,10 @@ class DocData {
 				doc.is_experimental = p_dict["is_experimental"];
 			}
 
+			if (p_dict.has("keywords")) {
+				doc.keywords = p_dict["keywords"];
+			}
+
 			return doc;
 		}
 		static Dictionary to_dict(const PropertyDoc &p_doc) {
@@ -432,6 +455,10 @@ class DocData {
 
 			dict["is_experimental"] = p_doc.is_experimental;
 
+			if (!p_doc.keywords.is_empty()) {
+				dict["keywords"] = p_doc.keywords;
+			}
+
 			return dict;
 		}
 	};
@@ -442,6 +469,7 @@ class DocData {
 		String data_type;
 		String description;
 		String default_value;
+		String keywords;
 		bool operator<(const ThemeItemDoc &p_theme_item) const {
 			// First sort by the data type, then by name.
 			if (data_type == p_theme_item.data_type) {
@@ -472,6 +500,10 @@ class DocData {
 				doc.default_value = p_dict["default_value"];
 			}
 
+			if (p_dict.has("keywords")) {
+				doc.keywords = p_dict["keywords"];
+			}
+
 			return doc;
 		}
 		static Dictionary to_dict(const ThemeItemDoc &p_doc) {
@@ -497,6 +529,10 @@ class DocData {
 				dict["default_value"] = p_doc.default_value;
 			}
 
+			if (!p_doc.keywords.is_empty()) {
+				dict["keywords"] = p_doc.keywords;
+			}
+
 			return dict;
 		}
 	};
@@ -573,6 +609,7 @@ class DocData {
 		String inherits;
 		String brief_description;
 		String description;
+		String keywords;
 		Vector<TutorialDoc> tutorials;
 		Vector<MethodDoc> constructors;
 		Vector<MethodDoc> methods;
@@ -609,6 +646,10 @@ class DocData {
 				doc.description = p_dict["description"];
 			}
 
+			if (p_dict.has("keywords")) {
+				doc.keywords = p_dict["keywords"];
+			}
+
 			Array tutorials;
 			if (p_dict.has("tutorials")) {
 				tutorials = p_dict["tutorials"];
@@ -816,6 +857,10 @@ class DocData {
 				dict["script_path"] = p_doc.script_path;
 			}
 
+			if (!p_doc.keywords.is_empty()) {
+				dict["keywords"] = p_doc.keywords;
+			}
+
 			return dict;
 		}
 	};

diff --git a/doc/class.xsd b/doc/class.xsd
@@ -101,6 +101,7 @@
 									<xs:attribute type="xs:string" name="qualifiers" use="optional" />
 									<xs:attribute type="xs:boolean" name="is_deprecated" use="optional" />
 									<xs:attribute type="xs:boolean" name="is_experimental" use="optional" />
+									<xs:attribute type="xs:string" name="keywords" use="optional" />
 								</xs:complexType>
 							</xs:element>
 						</xs:sequence>
@@ -123,6 +124,7 @@
 											<xs:attribute type="xs:string" name="default" use="optional" />
 											<xs:attribute type="xs:boolean" name="is_deprecated" use="optional" />
 											<xs:attribute type="xs:boolean" name="is_experimental" use="optional" />
+											<xs:attribute type="xs:string" name="keywords" use="optional" />
 										</xs:extension>
 									</xs:simpleContent>
 								</xs:complexType>
@@ -144,6 +146,7 @@
 												<xs:attribute type="xs:byte" name="index" />
 												<xs:attribute type="xs:string" name="name" />
 												<xs:attribute type="xs:string" name="type" />
+												<xs:attribute type="xs:string" name="keywords" use="optional" />
 											</xs:complexType>
 										</xs:element>
 										<xs:element type="xs:string" name="description" />
@@ -169,6 +172,7 @@
 											<xs:attribute type="xs:boolean" name="is_bitfield" use="optional" />
 											<xs:attribute type="xs:boolean" name="is_deprecated" use="optional" />
 											<xs:attribute type="xs:boolean" name="is_experimental" use="optional" />
+											<xs:attribute type="xs:string" name="keywords" use="optional" />
 										</xs:extension>
 									</xs:simpleContent>
 								</xs:complexType>
@@ -209,6 +213,7 @@
 									</xs:sequence>
 									<xs:attribute type="xs:string" name="name" use="optional" />
 									<xs:attribute type="xs:string" name="qualifiers" use="optional" />
+									<xs:attribute type="xs:string" name="keywords" use="optional" />
 								</xs:complexType>
 							</xs:element>
 						</xs:sequence>
@@ -225,6 +230,7 @@
 											<xs:attribute type="xs:string" name="data_type" />
 											<xs:attribute type="xs:string" name="type" />
 											<xs:attribute type="xs:string" name="default" use="optional" />
+											<xs:attribute type="xs:string" name="keywords" use="optional" />
 										</xs:extension>
 									</xs:simpleContent>
 								</xs:complexType>
@@ -275,6 +281,7 @@
 			<xs:attribute type="xs:string" name="inherits" />
 			<xs:attribute type="xs:boolean" name="is_deprecated" use="optional" />
 			<xs:attribute type="xs:boolean" name="is_experimental" use="optional" />
+			<xs:attribute type="xs:string" name="keywords" use="optional" />
 		</xs:complexType>
 	</xs:element>
 </xs:schema>
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py
@@ -166,6 +166,10 @@ def parse_class(self, class_root: ET.Element, filepath: str) -> None:
         if desc is not None and desc.text:
             class_def.description = desc.text
 
+        keywords = class_root.get("keywords")
+        if keywords is not None:
+            class_def.keywords = keywords
+
         properties = class_root.find("members")
         if properties is not None:
             for property in properties:
@@ -564,6 +568,7 @@ def __init__(self, name: str) -> None:
         self.brief_description: Optional[str] = None
         self.description: Optional[str] = None
         self.tutorials: List[Tuple[str, str]] = []
+        self.keywords: Optional[str] = None
 
         # Used to match the class with XML source for output filtering purposes.
         self.filepath: str = ""
@@ -866,6 +871,10 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
     # Remove the "Edit on Github" button from the online docs page.
     f.write(":github_url: hide\n\n")
 
+    # Add keywords metadata.
+    if class_def.keywords is not None and class_def.keywords != "":
+        f.write(f".. meta::\n\t:keywords: {class_def.keywords}\n\n")
+
     # Warn contributors not to edit this file directly.
     # Also provide links to the source files for reference.