From 2c5c3ae57927b1152d3c6066217fb4dfc756ddc5 Mon Sep 17 00:00:00 2001 From: David Snopek Date: Fri, 3 May 2024 10:34:04 -0500 Subject: [PATCH] Generate docs from GDExtensions using `--gdextension-docs` with `--doctool` --- editor/doc_tools.cpp | 18 +++++++++-------- editor/doc_tools.h | 2 +- main/main.cpp | 47 ++++++++++++++++++++++++++------------------ 3 files changed, 39 insertions(+), 28 deletions(-) diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp index d3875709ee4..7fce3c45f8f 100644 --- a/editor/doc_tools.cpp +++ b/editor/doc_tools.cpp @@ -1602,7 +1602,7 @@ static void _write_method_doc(Ref f, const String &p_name, Vector &p_class_path, bool p_include_xml_schema) { +Error DocTools::save_classes(const String &p_default_path, const HashMap &p_class_path, bool p_use_relative_schema) { for (KeyValue &E : class_list) { DocData::ClassDoc &c = E.value; @@ -1634,15 +1634,17 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap)", + schema_path); _write_string(f, 0, header); _write_string(f, 1, ""); diff --git a/editor/doc_tools.h b/editor/doc_tools.h index a6910baf282..3be59bf233c 100644 --- a/editor/doc_tools.h +++ b/editor/doc_tools.h @@ -52,7 +52,7 @@ public: }; void generate(BitField p_flags = {}); Error load_classes(const String &p_dir); - Error save_classes(const String &p_default_path, const HashMap &p_class_path, bool p_include_xml_schema = true); + Error save_classes(const String &p_default_path, const HashMap &p_class_path, bool p_use_relative_schema = true); Error _load(Ref parser); Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size); diff --git a/main/main.cpp b/main/main.cpp index 2def90bc1ae..e30584ebb97 100644 --- a/main/main.cpp +++ b/main/main.cpp @@ -637,6 +637,7 @@ void Main::print_help(const char *p_binary) { #endif // DISABLE_DEPRECATED print_help_option("--doctool [path]", "Dump the engine API reference to the given (defaults to current directory) in XML format, merging if existing files are found.\n", CLI_OPTION_AVAILABILITY_EDITOR); print_help_option("--no-docbase", "Disallow dumping the base types (used with --doctool).\n", CLI_OPTION_AVAILABILITY_EDITOR); + print_help_option("--gdextension-docs", "Rather than dumping the engine API, generate API reference from all the GDExtensions loaded in the current project (used with --doctool).\n", CLI_OPTION_AVAILABILITY_EDITOR); #ifdef MODULE_GDSCRIPT_ENABLED print_help_option("--gdscript-docs ", "Rather than dumping the engine API, generate API reference from the inline documentation in the GDScript files found in (used with --doctool).\n", CLI_OPTION_AVAILABILITY_EDITOR); #endif @@ -3214,6 +3215,9 @@ int Main::start() { #ifdef TOOLS_ENABLED } else if (E->get() == "--no-docbase") { gen_flags.set_flag(DocTools::GENERATE_FLAG_SKIP_BASIC_TYPES); + } else if (E->get() == "--gdextension-docs") { + gen_flags.set_flag(DocTools::GENERATE_FLAG_SKIP_BASIC_TYPES); + gen_flags.set_flag(DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY); #ifndef DISABLE_DEPRECATED } else if (E->get() == "--convert-3to4") { converting_project = true; @@ -3340,29 +3344,34 @@ int Main::start() { HashSet checked_paths; print_line("Loading docs..."); - for (int i = 0; i < _doc_data_class_path_count; i++) { - // Custom modules are always located by absolute path. - String path = _doc_data_class_paths[i].path; - if (path.is_relative_path()) { - path = doc_tool_path.path_join(path); - } - String name = _doc_data_class_paths[i].name; - doc_data_classes[name] = path; - if (!checked_paths.has(path)) { - checked_paths.insert(path); + const bool gdextension_docs = gen_flags.has_flag(DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY); - // Create the module documentation directory if it doesn't exist - Ref da = DirAccess::create_for_path(path); - err = da->make_dir_recursive(path); - ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error: Can't create directory: " + path + ": " + itos(err)); + if (!gdextension_docs) { + for (int i = 0; i < _doc_data_class_path_count; i++) { + // Custom modules are always located by absolute path. + String path = _doc_data_class_paths[i].path; + if (path.is_relative_path()) { + path = doc_tool_path.path_join(path); + } + String name = _doc_data_class_paths[i].name; + doc_data_classes[name] = path; + if (!checked_paths.has(path)) { + checked_paths.insert(path); - print_line("Loading docs from: " + path); - err = docsrc.load_classes(path); - ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error loading docs from: " + path + ": " + itos(err)); + // Create the module documentation directory if it doesn't exist + Ref da = DirAccess::create_for_path(path); + err = da->make_dir_recursive(path); + ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error: Can't create directory: " + path + ": " + itos(err)); + + print_line("Loading docs from: " + path); + err = docsrc.load_classes(path); + ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error loading docs from: " + path + ": " + itos(err)); + } } } - String index_path = doc_tool_path.path_join("doc/classes"); + // For GDExtension docs, use a path that is compatible with Godot modules. + String index_path = gdextension_docs ? doc_tool_path.path_join("doc_classes") : doc_tool_path.path_join("doc/classes"); // Create the main documentation directory if it doesn't exist Ref da = DirAccess::create_for_path(index_path); err = da->make_dir_recursive(index_path); @@ -3383,7 +3392,7 @@ int Main::start() { } print_line("Generating new docs..."); - err = doc.save_classes(index_path, doc_data_classes); + err = doc.save_classes(index_path, doc_data_classes, !gdextension_docs); ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error saving new docs:" + itos(err)); print_line("Deleting docs cache...");