Skip to content

Commit ec78dde

Browse files
akien-mgaakien-mga
committed
Merge pull request #91518 from dsnopek/doctool-gdextension-docs
Generate docs from GDExtensions using `--gdextension-docs` with `--doctool`
2 parents 316b87d + 2c5c3ae commit ec78dde

File tree

3 files changed

+41
-30
lines changed

3 files changed

+41
-30
lines changed

‎editor/doc_tools.cpp

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1602,7 +1602,7 @@ static void _write_method_doc(Ref<FileAccess> f, const String &p_name, Vector<Do
16021602
}
16031603
}
16041604

1605-
Error DocTools::save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_include_xml_schema) {
1605+
Error DocTools::save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_use_relative_schema) {
16061606
for (KeyValue<String, DocData::ClassDoc> &E : class_list) {
16071607
DocData::ClassDoc &c = E.value;
16081608

@@ -1634,15 +1634,17 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap<String,
16341634
if (!c.keywords.is_empty()) {
16351635
header += String(" keywords=\"") + c.keywords.xml_escape(true) + "\"";
16361636
}
1637-
if (p_include_xml_schema) {
1638-
// Reference the XML schema so editors can provide error checking.
1637+
// Reference the XML schema so editors can provide error checking.
1638+
String schema_path;
1639+
if (p_use_relative_schema) {
16391640
// Modules are nested deep, so change the path to reference the same schema everywhere.
1640-
const String schema_path = save_path.find("modules/") != -1 ? "../../../doc/class.xsd" : "../class.xsd";
1641-
header += vformat(
1642-
R"( xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="%s")",
1643-
schema_path);
1641+
schema_path = save_path.find("modules/") != -1 ? "../../../doc/class.xsd" : "../class.xsd";
1642+
} else {
1643+
schema_path = "https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd";
16441644
}
1645-
header += ">";
1645+
header += vformat(
1646+
R"( xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="%s">)",
1647+
schema_path);
16461648
_write_string(f, 0, header);
16471649

16481650
_write_string(f, 1, "<brief_description>");

‎editor/doc_tools.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ class DocTools {
5252
};
5353
void generate(BitField<GenerateFlags> p_flags = {});
5454
Error load_classes(const String &p_dir);
55-
Error save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_include_xml_schema = true);
55+
Error save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_use_relative_schema = true);
5656

5757
Error _load(Ref<XMLParser> parser);
5858
Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size);

‎main/main.cpp

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -637,6 +637,7 @@ void Main::print_help(const char *p_binary) {
637637
#endif // DISABLE_DEPRECATED
638638
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);
639639
print_help_option("--no-docbase", "Disallow dumping the base types (used with --doctool).\n", CLI_OPTION_AVAILABILITY_EDITOR);
640+
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);
640641
#ifdef MODULE_GDSCRIPT_ENABLED
641642
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);
642643
#endif
@@ -3214,6 +3215,9 @@ int Main::start() {
32143215
#ifdef TOOLS_ENABLED
32153216
} else if (E->get() == "--no-docbase") {
32163217
gen_flags.set_flag(DocTools::GENERATE_FLAG_SKIP_BASIC_TYPES);
3218+
} else if (E->get() == "--gdextension-docs") {
3219+
gen_flags.set_flag(DocTools::GENERATE_FLAG_SKIP_BASIC_TYPES);
3220+
gen_flags.set_flag(DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY);
32173221
#ifndef DISABLE_DEPRECATED
32183222
} else if (E->get() == "--convert-3to4") {
32193223
converting_project = true;
@@ -3340,29 +3344,34 @@ int Main::start() {
33403344
HashSet<String> checked_paths;
33413345
print_line("Loading docs...");
33423346

3343-
for (int i = 0; i < _doc_data_class_path_count; i++) {
3344-
// Custom modules are always located by absolute path.
3345-
String path = _doc_data_class_paths[i].path;
3346-
if (path.is_relative_path()) {
3347-
path = doc_tool_path.path_join(path);
3348-
}
3349-
String name = _doc_data_class_paths[i].name;
3350-
doc_data_classes[name] = path;
3351-
if (!checked_paths.has(path)) {
3352-
checked_paths.insert(path);
3353-
3354-
// Create the module documentation directory if it doesn't exist
3355-
Ref<DirAccess> da = DirAccess::create_for_path(path);
3356-
err = da->make_dir_recursive(path);
3357-
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error: Can't create directory: " + path + ": " + itos(err));
3358-
3359-
print_line("Loading docs from: " + path);
3360-
err = docsrc.load_classes(path);
3361-
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error loading docs from: " + path + ": " + itos(err));
3347+
const bool gdextension_docs = gen_flags.has_flag(DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY);
3348+
3349+
if (!gdextension_docs) {
3350+
for (int i = 0; i < _doc_data_class_path_count; i++) {
3351+
// Custom modules are always located by absolute path.
3352+
String path = _doc_data_class_paths[i].path;
3353+
if (path.is_relative_path()) {
3354+
path = doc_tool_path.path_join(path);
3355+
}
3356+
String name = _doc_data_class_paths[i].name;
3357+
doc_data_classes[name] = path;
3358+
if (!checked_paths.has(path)) {
3359+
checked_paths.insert(path);
3360+
3361+
// Create the module documentation directory if it doesn't exist
3362+
Ref<DirAccess> da = DirAccess::create_for_path(path);
3363+
err = da->make_dir_recursive(path);
3364+
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error: Can't create directory: " + path + ": " + itos(err));
3365+
3366+
print_line("Loading docs from: " + path);
3367+
err = docsrc.load_classes(path);
3368+
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error loading docs from: " + path + ": " + itos(err));
3369+
}
33623370
}
33633371
}
33643372

3365-
String index_path = doc_tool_path.path_join("doc/classes");
3373+
// For GDExtension docs, use a path that is compatible with Godot modules.
3374+
String index_path = gdextension_docs ? doc_tool_path.path_join("doc_classes") : doc_tool_path.path_join("doc/classes");
33663375
// Create the main documentation directory if it doesn't exist
33673376
Ref<DirAccess> da = DirAccess::create_for_path(index_path);
33683377
err = da->make_dir_recursive(index_path);
@@ -3383,7 +3392,7 @@ int Main::start() {
33833392
}
33843393

33853394
print_line("Generating new docs...");
3386-
err = doc.save_classes(index_path, doc_data_classes);
3395+
err = doc.save_classes(index_path, doc_data_classes, !gdextension_docs);
33873396
ERR_FAIL_COND_V_MSG(err != OK, EXIT_FAILURE, "Error saving new docs:" + itos(err));
33883397

33893398
print_line("Deleting docs cache...");

0 commit comments

Comments
 (0)