From 564196394ba83ae77ea089e32961c87350b232a3 Mon Sep 17 00:00:00 2001 From: Relintai Date: Sat, 6 Jan 2024 13:41:33 +0100 Subject: [PATCH] Rework the doc tool a bit. Now it need a new template which needs to have classes added manually, and it will generate a list from the unused classes. --- tools/doc/index_remaining_template.md.html | 162 +++++++++++++++++++++ tools/doc/index_template.md.html | 19 +++ tools/doc/main.cpp | 90 ++++++++++-- 3 files changed, 262 insertions(+), 9 deletions(-) create mode 100644 tools/doc/index_remaining_template.md.html diff --git a/tools/doc/index_remaining_template.md.html b/tools/doc/index_remaining_template.md.html new file mode 100644 index 0000000..8a7da2e --- /dev/null +++ b/tools/doc/index_remaining_template.md.html @@ -0,0 +1,162 @@ + + **Sample API Doc** + 1.1 Release + + +This is the markdeep generic "Company API" template. Replace +`company-logo-512.png` with your organization's logo and adjust the +`company-api.css` styling to match the desired colors. + +See `CA::OpenHandle()` for an example of an auto-generated API link. +The rest of the information on this page is bogus placeholder to show the formatting. + + +API Modules +==================================================================================== + +The CA library is a layer on top of the resource manager and parsing libraries that +provides utilities for streaming processing and client-side process construction. + + +ENUMS +==================================================================================== + +$ENUMS$ + +STRUCTS +==================================================================================== + +$STRUCTS$ + +CLASSES +==================================================================================== + +$CLASSES$ + +Modules +---------------------------------------------------------------------------------------- + +The CA library contains the APIs for applications to allocate and exchange resources. + + +!!! Attention Attention + Always read all of the documentation. + +[CA APIs](#CA) +: List of APIs to manage external processes. + +CA Buffer List APIs +: Methods to process buffer resources separate from computation. + +CA Data Structures +: Specifies the data structures used for complex cases. + + +## Handles + +`CA::OpenHandle(const std::string&)` +: Open a reference handle. + +`CA::ReadMetaData(const Handle&)` +: Metadata about the event. + +`CA::CloseHandle(const Handle&)` +: Free all handle resources, recursively. + + +CA +==================================================================================== + +!!! Warning Warning + The API content represents the set of APIs you can use directly. Some APIs + are not documented and we advise you do not use them directly. Using undocumented + APIs can lead to incompatibility when upgrading to later releases. + + +These examples assume that your directory structure is: + +********************************************************** +* +* 📂 ca1 +* | +* +-- 📄 bar.txt +* | +* +-- 📂 foo +* | | +* | ⋮ +* | +* +-- 📂 xsource +* | | +* | +-- 📂 data +* | | | +* | | +-- 📄 manifest.json +* | | | +* | ⋮ ⋮ +* | +* ⋮ +********************************************************** +[Directory structure.] + + +Table +------------------------------------------------------------------ + + +Screen | Factor | Used | Efficiency +----------:|------------:|----------:|---------: +1366x768 | 3x | 1152x672 | 74% +1440x900 | 3x | 1152x672 | 60% +*1600x900* | *4x* | 1536x896 | *96%* +1680x1050 | 4x | 1536x896 | 78% +1920x1080 | 4x | 1536x896 | 66% +*1920x1200*| *5x* | 1920x1120 | *93%* +[A Table] + + +More Info +------------------------------------------------------------------ + +****************************************************************** +* ^ y +* | +* .---------. .----|----. +* | | | | | +* | *-------> x | *--------> x +* | | | | | +* '----|----' '---------' +* | +* v y +****************************************************************** +[Figure 1: Coordinate Example] + + + ----- + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL +vec3 sphNormal(in vec3 pos, in vec4 sph) { + return normalize(pos-sph.xyz); +} + +vec3 camera(vec2 U, vec2 r, vec3 ro, vec3 la, float fl) { + vec2 uv = (U - r*.5)/r.y; + vec3 fwd = normalize(la-ro), + rgt = normalize(vec3(fwd.z, 0., -fwd.x)); + return normalize(fwd + fl*uv.x*rgt + fl*uv.y*cross(fwd, rgt)); +} + +float vMap(vec3 p) { + float hit = 0.0; + vec2 h2 = hash22(floor(p.xz*0.25)); + if (p.z > 0.0) { + if (p.y < -10.0 && h2.x > 0.5) hit=1.0; + if (p.y > 10.0 && h2.y > 0.5) hit=1.0; + } + return hit; +} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +[Code listing] + + + + + diff --git a/tools/doc/index_template.md.html b/tools/doc/index_template.md.html index 8a7da2e..6d9c2a6 100644 --- a/tools/doc/index_template.md.html +++ b/tools/doc/index_template.md.html @@ -11,6 +11,25 @@ See `CA::OpenHandle()` for an example of an auto-generated API link. The rest of the information on this page is bogus placeholder to show the formatting. + + + + +ENUMS +==================================================================================== + + +ClockDirection +---------------------------------------------------------------------------------------- + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ +|||ENUM_ClockDirection||| +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + + + API Modules ==================================================================================== diff --git a/tools/doc/main.cpp b/tools/doc/main.cpp index 665d1ec..ebcbb5c 100644 --- a/tools/doc/main.cpp +++ b/tools/doc/main.cpp @@ -7,6 +7,12 @@ void print_list(const List &list) { } } +void print_class_index_keys(const HashMap &class_index) { + for (const HashMap::Element *E = class_index.front(); E; E = E->next) { + ERR_PRINT(E->key()); + } +} + String get_structure_name(const String &data) { String fl = data.get_slicec('{', 0); String l = fl.get_slicec('\n', fl.get_slice_count("\n") - 1); @@ -43,7 +49,7 @@ bool is_structure_template_specialization_or_parent_is_template(const String &da return get_structure_parents(data).contains("<"); } -String generate_section_class_list(const List &list) { +String generate_section_class_list(const List &list, const String &cls_prefix, const HashSet &used_keywords) { FileAccess f; String code_template = f.read_file("code_template.md.html"); String d; @@ -53,17 +59,53 @@ String generate_section_class_list(const List &list) { String sname = get_structure_name(c); - if (sname.empty() || sname.begins_with("_")) { + if (sname.empty()) { //ERR_PRINT(sname); continue; } + if (used_keywords.has(cls_prefix + sname)) { + continue; + } + d += code_template.replace("$CODE$", c).replace("$NAME$", sname); } return d; } +void generate_class_index(const List &list, const String &cls_prefix, HashMap *cls_index) { + ERR_FAIL_COND(!cls_index); + + for (const List::Element *E = list.front(); E; E = E->next()) { + String c = E->get(); + + String sname = get_structure_name(c); + + if (sname.empty()) { + //ERR_PRINT(sname); + continue; + } + + (*cls_index)[cls_prefix + sname] = c; + } +} + +List get_template_keywords(const String &tmpl) { + List ret; + + //awful, but oh well + Vector sp = tmpl.split("|||"); + + ERR_FAIL_COND_V_MSG(sp.size() % 2 == 0, ret, "Template has unterminated keywords!"); + + for (int i = 1; i < sp.size(); i += 2) { + ret.push_back(sp[i]); + } + + return ret; +} + List process_classes_and_structs(const List &list) { List ret; @@ -330,7 +372,7 @@ void process_file(const String &path) { //Not we should be able to do this, because of how the code style is if (l.contains("enum ") && l.contains("{")) { if (l.contains("}")) { - enums.push_back(current_str); + enums.push_back(current_str.strip_edges()); //ERR_PRINT("TYPE_ENUM"); //ERR_PRINT(current_str); current_str.clear(); @@ -388,7 +430,7 @@ void process_file(const String &path) { //cant happen break; case TYPE_ENUM: - enums.push_back(current_str); + enums.push_back(current_str.strip_edges()); //ERR_PRINT("TYPE_ENUM"); break; case TYPE_STRUCT: @@ -461,12 +503,42 @@ void process_file(const String &path) { //ERR_PRINT(itos(structs.size())); //ERR_PRINT(itos(classes.size())); - String index_template = f.read_file("index_template.md.html"); - String d = index_template; + HashMap class_index; - d = d.replace("$ENUMS$", generate_section_class_list(enums)); - d = d.replace("$STRUCTS$", generate_section_class_list(structs)); - d = d.replace("$CLASSES$", generate_section_class_list(classes)); + generate_class_index(enums, "ENUM_", &class_index); + generate_class_index(structs, "STRUCT_", &class_index); + generate_class_index(classes, "CLASS_", &class_index); + + //print_class_index_keys(class_index); + + String index_template = f.read_file("index_template.md.html"); + List index_template_keywords = get_template_keywords(index_template); + HashSet used_keywords; + + //print_list(index_template_keywords); + + String index_str = index_template; + + for (const List::Element *E = index_template_keywords.front(); E; E = E->next()) { + String c = E->get(); + + ERR_CONTINUE_MSG(!class_index.has(c), "!class_index.has(): " + c); + + String keyword = "|||" + E->get() + "|||"; + + index_str = index_str.replace(keyword, class_index[c]); + used_keywords.insert(c); + } + + f.write_file("out/index.md.html", index_str); + + //Generate a list from the unused classes. + String index_remaining_template = f.read_file("index_remaining_template.md.html"); + String d = index_remaining_template; + + d = d.replace("$ENUMS$", generate_section_class_list(enums, "ENUM_", used_keywords)); + d = d.replace("$STRUCTS$", generate_section_class_list(structs, "STRUCT_", used_keywords)); + d = d.replace("$CLASSES$", generate_section_class_list(classes, "CLASS_", used_keywords)); f.write_file("out/index_remaining.gen.md.html", d); }