Nixyri/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2024-11-10 06:03:09 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Generate docs from GDExtensions using --gdextension-docs with --doctool

Browse Source
This commit is contained in:
David Snopek 2024-05-03 10:34:04 -05:00
parent 55b8724bd5
commit 2c5c3ae579
3 changed files with 39 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
editor/doc_tools.cpp
View File

@ -1602,7 +1602,7 @@ static void _write_method_doc(Ref<FileAccess> f, const String &p_name, Vector<Do
} }
} }
Error DocTools::save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_include_xml_schema) { Error DocTools::save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_use_relative_schema) {
for (KeyValue<String, DocData::ClassDoc> &E : class_list) { for (KeyValue<String, DocData::ClassDoc> &E : class_list) {
DocData::ClassDoc &c = E.value; DocData::ClassDoc &c = E.value;
@ -1634,15 +1634,17 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap<String,
if (!c.keywords.is_empty()) { if (!c.keywords.is_empty()) {
header += String(" keywords=\"") + c.keywords.xml_escape(true) + "\""; header += String(" keywords=\"") + c.keywords.xml_escape(true) + "\"";
} }
if (p_include_xml_schema) { // Reference the XML schema so editors can provide error checking.
// Reference the XML schema so editors can provide error checking. String schema_path;
if (p_use_relative_schema) {
// Modules are nested deep, so change the path to reference the same schema everywhere. // Modules are nested deep, so change the path to reference the same schema everywhere.
const String schema_path = save_path.find("modules/") != -1 ? "../../../doc/class.xsd" : "../class.xsd"; schema_path = save_path.find("modules/") != -1 ? "../../../doc/class.xsd" : "../class.xsd";
header += vformat( } else {
R"( xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="%s")", schema_path = "https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd";
schema_path);
} }
header += ">"; header += vformat(
R"( xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="%s">)",
schema_path);
_write_string(f, 0, header); _write_string(f, 0, header);
_write_string(f, 1, "<brief_description>"); _write_string(f, 1, "<brief_description>");

2
editor/doc_tools.h
View File

@ -52,7 +52,7 @@ public:
}; };
void generate(BitField<GenerateFlags> p_flags = {}); void generate(BitField<GenerateFlags> p_flags = {});
Error load_classes(const String &p_dir); Error load_classes(const String &p_dir);
Error save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_include_xml_schema = true); Error save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_use_relative_schema = true);
Error _load(Ref<XMLParser> parser); Error _load(Ref<XMLParser> parser);
Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size); Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size);

47
main/main.cpp
View File

@ -637,6 +637,7 @@ void Main::print_help(const char *p_binary) {
#endif // DISABLE_DEPRECATED #endif // DISABLE_DEPRECATED
print_help_option("--doctool [path]", "Dump the engine API reference to the given <path> (defaults to current directory) in XML format, merging if existing files are found.\n", CLI_OPTION_AVAILABILITY_EDITOR); print_help_option("--doctool [path]", "Dump the engine API reference to the given <path> (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("--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 #ifdef MODULE_GDSCRIPT_ENABLED
print_help_option("--gdscript-docs <path>", "Rather than dumping the engine API, generate API reference from the inline documentation in the GDScript files found in <path> (used with --doctool).\n", CLI_OPTION_AVAILABILITY_EDITOR); print_help_option("--gdscript-docs <path>", "Rather than dumping the engine API, generate API reference from the inline documentation in the GDScript files found in <path> (used with --doctool).\n", CLI_OPTION_AVAILABILITY_EDITOR);
#endif #endif
@ -3214,6 +3215,9 @@ int Main::start() {
#ifdef TOOLS_ENABLED #ifdef TOOLS_ENABLED
} else if (E->get() == "--no-docbase") { } else if (E->get() == "--no-docbase") {
gen_flags.set_flag(DocTools::GENERATE_FLAG_SKIP_BASIC_TYPES); 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 #ifndef DISABLE_DEPRECATED
} else if (E->get() == "--convert-3to4") { } else if (E->get() == "--convert-3to4") {
converting_project = true; converting_project = true;
@ -3340,29 +3344,34 @@ int Main::start() {
HashSet<String> checked_paths; HashSet<String> checked_paths;
print_line("Loading docs..."); print_line("Loading docs...");
for (int i = 0; i < _doc_data_class_path_count; i++) { const bool gdextension_docs = gen_flags.has_flag(DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY);
// 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);
// Create the module documentation directory if it doesn't exist if (!gdextension_docs) {
Ref<DirAccess> da = DirAccess::create_for_path(path); for (int i = 0; i < _doc_data_class_path_count; i++) {
err = da->make_dir_recursive(path); // Custom modules are always located by absolute path.
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error: Can't create directory: " + path + ": " + itos(err)); 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); // Create the module documentation directory if it doesn't exist
err = docsrc.load_classes(path); Ref<DirAccess> da = DirAccess::create_for_path(path);
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error loading docs from: " + path + ": " + itos(err)); 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 // Create the main documentation directory if it doesn't exist
Ref<DirAccess> da = DirAccess::create_for_path(index_path); Ref<DirAccess> da = DirAccess::create_for_path(index_path);
err = da->make_dir_recursive(index_path); err = da->make_dir_recursive(index_path);
@ -3383,7 +3392,7 @@ int Main::start() {
} }
print_line("Generating new docs..."); 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)); ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error saving new docs:" + itos(err));
print_line("Deleting docs cache..."); print_line("Deleting docs cache...");