diff options
| -rwxr-xr-x | doc/tools/make_rst.py | 104 |
1 files changed, 99 insertions, 5 deletions
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 82d4ddb3b2..4f41baebf7 100755 --- a/doc/tools/make_rst.py +++ b/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. |