Merge pull request #63497 from YuriSizov/docs-split-classref

Split generated RST for class reference based on the base type

doc/tools/make_rst.py

@@ -29,6 +29,10 @@ MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>"
 # write in this script (check `translate()` uses), and also hardcoded in
 # `doc/translations/extract.py` to include them in the source POT file.
 BASE_STRINGS = [
+    "Objects",
+    "Nodes",
+    "Resources",
+    "Globals",
     "Description",
     "Tutorials",
     "Properties",
@@ -63,6 +67,13 @@ strings_l10n: Dict[str, str] = {}
 
 STYLES: Dict[str, str] = {}
 
+CLASS_GROUPS: Dict[str, str] = {
+    "global": "Globals",
+    "node": "Nodes",
+    "resource": "Resources",
+    "class": "Objects",
+}
+
 
 class State:
     def __init__(self) -> None:
@@ -329,7 +340,7 @@ class State:
         return cast
 
     def sort_classes(self) -> None:
-        self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0]))
+        self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0].lower()))
 
 
 class TypeName:
@@ -601,12 +612,25 @@ def main() -> None:
 
     print("Generating the RST class reference...")
 
+    grouped_classes: Dict[str, List[str]] = {}
+
     for class_name, class_def in state.classes.items():
         if args.filter and not pattern.search(class_def.filepath):
             continue
         state.current_class = class_name
         make_rst_class(class_def, state, args.dry_run, args.output)
 
+        group_name = get_class_group(class_def, state)
+
+        if group_name not in grouped_classes:
+            grouped_classes[group_name] = []
+        grouped_classes[group_name].append(class_name)
+
+    print("")
+    print("Generating the index file...")
+
+    make_rst_index(grouped_classes, args.dry_run, args.output)
+
     print("")
 
     if state.num_warnings >= 2:
@@ -655,6 +679,39 @@ def translate(string: str) -> str:
     return strings_l10n.get(string, string)
 
 
+def get_git_branch() -> str:
+    if hasattr(version, "docs") and version.docs != "latest":
+        return version.docs
+
+    return "master"
+
+
+def get_class_group(class_def: ClassDef, state: State) -> str:
+    group_name = "class"
+    class_name = class_def.name
+
+    if class_name.startswith("@"):
+        group_name = "global"
+    elif class_def.inherits:
+        inherits = class_def.inherits.strip()
+
+        while inherits in state.classes:
+            if inherits == "Node":
+                group_name = "node"
+                break
+            if inherits == "Resource":
+                group_name = "resource"
+                break
+
+            inode = state.classes[inherits].inherits
+            if inode:
+                inherits = inode.strip()
+            else:
+                break
+
+    return group_name
+
+
 # Generator methods.
 
 
@@ -672,10 +729,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
     # Warn contributors not to edit this file directly.
     # Also provide links to the source files for reference.
 
-    git_branch = "master"
-    if hasattr(version, "docs") and version.docs != "latest":
-        git_branch = version.docs
-
+    git_branch = get_git_branch()
     source_xml_path = os.path.relpath(class_def.filepath, root_directory).replace("\\", "/")
     source_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/{source_xml_path}"
     generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py"
@@ -1205,6 +1259,46 @@ def make_link(url: str, title: str) -> str:
     return f"`{url} <{url}>`__"
 
 
+def make_rst_index(grouped_classes: Dict[str, List[str]], dry_run: bool, output_dir: str) -> None:
+
+    if dry_run:
+        f = open(os.devnull, "w", encoding="utf-8")
+    else:
+        f = open(os.path.join(output_dir, "index.rst"), "w", encoding="utf-8")
+
+    # Remove the "Edit on Github" button from the online docs page.
+    f.write(":github_url: hide\n\n")
+
+    # Warn contributors not to edit this file directly.
+    # Also provide links to the source files for reference.
+
+    git_branch = get_git_branch()
+    generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py"
+
+    f.write(".. DO NOT EDIT THIS FILE!!!\n")
+    f.write(".. Generated automatically from Godot engine sources.\n")
+    f.write(f".. Generator: {generator_github_url}.\n\n")
+
+    f.write(".. _doc_class_reference:\n\n")
+
+    for group_name in CLASS_GROUPS:
+        if group_name in grouped_classes:
+            group_title = translate(CLASS_GROUPS[group_name])
+
+            f.write(f"{group_title}\n")
+            f.write(f"{'=' * len(group_title)}\n\n")
+
+            f.write(".. toctree::\n")
+            f.write("    :maxdepth: 1\n")
+            f.write("    :name: toc-class-ref-globals\n")
+            f.write("\n")
+
+            for class_name in grouped_classes[group_name]:
+                f.write(f"    class_{class_name.lower()}\n")
+
+            f.write("\n")
+
+
 # Formatting helpers.