Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
May 7, 2024
+41 −30
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
18 changes: 10 additions & 8 deletions editor/doc_tools.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
DocData::ClassDoc &c = E.value;

Expand Down Expand Up @@ -1634,15 +1634,17 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap<String,
if (!c.keywords.is_empty()) {
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.
const String schema_path = save_path.find("modules/") != -1 ? "../../../doc/class.xsd" : "../class.xsd";
header += vformat(
R"( xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="%s")",
schema_path);
schema_path = save_path.find("modules/") != -1 ? "../../../doc/class.xsd" : "../class.xsd";
} else {
schema_path = "https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd";
}
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, 1, "<brief_description>");
Expand Down
2 changes: 1 addition & 1 deletion editor/doc_tools.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ class DocTools {
};
void generate(BitField<GenerateFlags> p_flags = {});
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_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size);
Expand Down
51 changes: 30 additions & 21 deletions main/main.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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("--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 <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
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -3340,29 +3344,34 @@ int Main::start() {
HashSet<String> 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);

// Create the module documentation directory if it doesn't exist
Ref<DirAccess> 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));
const bool gdextension_docs = gen_flags.has_flag(DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY);

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;
Copy link
Contributor

@paddy-exe paddy-exe May 6, 2024 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just had a look at this again. Could this also be a const?
const String path = _doc_data_class_paths[i].path;?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's pre-existing code (only indentation changed here), but yes it could be const.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one actually can't be const because it's written to in the following two lines:

				if (path.is_relative_path()) {
					path = doc_tool_path.path_join(path);
				}

However, the name variable the next line down, could be const, I think. That said, since this PR is just indenting this, I'd prefer to leave the code in this block as is.

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
Ref<DirAccess> 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<DirAccess> da = DirAccess::create_for_path(index_path);
err = da->make_dir_recursive(index_path);
Expand All @@ -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...");
Expand Down