Add inheriting classes to `DocTools` #77554

AThousandShips · 2023-05-27T18:39:39Z

Integrating a documentation hierarchy into DocTools

Part of the work for #77471 and #62524, see there for the discussions and background

Edit: I believe this is ready

Fixes: Documentation: @GDScript and @GlobalScope are at the bottom of the list #63799

YuriSizov · 2023-05-29T11:22:15Z

Still working on deciding how to deal with the ordering searches, as this changes the previous order which put Object at the top, if maintaining that order is important I can rework it

Order should be alphabetical, so global scopes go at the top and then everything else is in their case-independent alphanumerical order (natural, perhaps?). This is something that I've been working on, actually, when I stumbled upon your work :) So if you actually manage to address this issue here, that's an amazing improvement!

AThousandShips · 2023-05-29T11:24:43Z

Will change the ordering to natural, I think there's a helper already for it! Sounds great

Bonus: unlike before new classes will end up in the right place in both search and the header of the help page, where before they were at the end

Note that at least currently this is not true for searching without hierarchy, as it uses the order in class_list, and can't easily resolve that here, #77213 would help with this

AThousandShips · 2023-05-29T12:05:06Z

We could use case sensitive natural sorting, but I think in this case this is sufficient, I'm not sure which order is preferred:

Light3D
LightmapProbe
LightOccluder3D

or:

Light3D
LightOccluder3D
LightmapProbe

YuriSizov · 2023-05-29T12:19:15Z

I'd say the first one makes more sense when you search for something by the name. Either way, we can try and see if there are complaints.

AThousandShips · 2023-07-13T09:43:12Z

I think this stage is ready for review properly now, and will continue to investigate the wider help indexing system as I am able

AThousandShips · 2023-07-13T13:55:05Z

Might solve #66407, will test

Seems to still be an intermittent problem, will try investigate

Edit: Does not solve it, seems to be caused by issues with the parser and circular references and don't think any implementation here can solve it, it appears to be that the inheriting data in the documentation is not correctly assigned if the parent class has cyclic errors like this, would require some more complicated updates to the data in the docgen for GDScript, so out of scope for this

akien-mga · 2023-09-08T11:37:38Z

Would you have a screenshot of the result?

AThousandShips · 2023-09-08T11:40:15Z

Will provide, for the correct order of sorted inherited classes?

akien-mga · 2023-09-08T11:41:48Z

Well I'm not 100% sure what this PR changes but I'm assuming there's a before/after for the EditorHelp changes?

AThousandShips · 2023-09-08T11:43:03Z

This makes the hierarchy of inherited classes explicitly available in DocTools, which improves the sorting, and makes the accessing of the inheriting classes easier to access, for example when generating the doc view, it is also part of a larger documentation enhancement where the access to that is convenient

The direct benefit is avoiding scanning the entire class list in order to figure out inherited classes, and also a building block for handling the same

Will provide screenshot for the sorting

Edit: Forgot it also makes help search sorted alphabetically

Before:

After:

AThousandShips · 2023-09-08T11:48:31Z

editor/editor_help.cpp

+ if ((cd.is_script_doc || ClassDB::class_exists(cd.name)) && doc->inheriting.has(cd.name)) {
 _push_normal_font();
- for (const KeyValue<String, DocData::ClassDoc> &E : doc->class_list) {
- if (E.value.inherits == cd.name) {
- if (!found) {
- class_desc->push_color(theme_cache.title_color);
- class_desc->add_text(TTR("Inherited by:") + " ");
- found = true;
- }
+ class_desc->push_color(theme_cache.title_color);
+ class_desc->add_text(TTR("Inherited by:") + " ");

- if (prev) {
- class_desc->add_text(" , ");
- }
- _add_type_icon(E.value.name, theme_cache.doc_font_size, "ArrowRight");
- class_desc->add_text(non_breaking_space); // Otherwise icon borrows hyperlink from _add_type().
- _add_type(E.value.name);
- prev = true;
+ for (RBSet<String, NaturalNoCaseComparator>::Element *itr = doc->inheriting[cd.name].front(); itr; itr = itr->next()) {
+ if (itr->prev()) {
+ class_desc->add_text(" , ");
 }
+
+ _add_type_icon(itr->get(), theme_cache.doc_font_size, "ArrowRight");
+ class_desc->add_text(non_breaking_space); // Otherwise icon borrows hyperlink from _add_type().
+ _add_type(itr->get());
 }
 _pop_normal_font();


This is the relevant change for that, which also avoids scanning the entire class list for all classes just to find inheriting ones

editor/doc_tools.cpp

YuriSizov

This looks great to me, love the new ordered list very much!

Some minor notes remain, and I'm also not great with data structures, so maybe @KoBeWi could take a quick look. But overall it all seems sensible.

PS. We should improve at some point the relevance of what is selected as the closest match, I think. Typing "path" with "Display All", for example, selects the first complete match which is a property of a navigation server struct. Very unlikely to be relevant.

godot windows editor dev x86_64_2024-01-16_14-29-02

editor/editor_help.cpp

editor/editor_help_search.cpp

AThousandShips · 2024-01-16T13:39:26Z

Will see about the relevance part in the final part, unsure how to improve it but good point!

akien-mga · 2024-01-16T15:48:29Z

Thanks!

AThousandShips · 2024-01-16T15:49:27Z

Thank you! Great to have this one done with

AThousandShips changed the title ~~Add inheriting classes to DocData~~ Add inheriting classes to DocTools May 27, 2023

Calinou added enhancement topic:editor labels May 27, 2023

Calinou added this to the 4.x milestone May 27, 2023

AThousandShips mentioned this pull request May 28, 2023

Cache TreeItems between runs in EditorHelpSearch #77471

Merged

YuriSizov self-requested a review May 29, 2023 11:22

AThousandShips force-pushed the doc_hierarchy branch from d9e89b4 to ec38a1e Compare May 29, 2023 11:52

AThousandShips marked this pull request as ready for review May 29, 2023 12:20

AThousandShips force-pushed the doc_hierarchy branch from ec38a1e to e9b4801 Compare July 13, 2023 09:38

AThousandShips force-pushed the doc_hierarchy branch from e9b4801 to 7c5c354 Compare August 16, 2023 12:01

AThousandShips force-pushed the doc_hierarchy branch from 7c5c354 to 33df4c3 Compare September 8, 2023 11:21

AThousandShips commented Sep 8, 2023

View reviewed changes

YuriSizov modified the milestones: 4.x, 4.3 Sep 27, 2023

AThousandShips force-pushed the doc_hierarchy branch from 33df4c3 to ea40ac2 Compare November 5, 2023 11:35

AThousandShips force-pushed the doc_hierarchy branch 2 times, most recently from 80a7b38 to ae34661 Compare December 7, 2023 12:19

AThousandShips mentioned this pull request Dec 7, 2023

EditorHelpSearch improvements #62524

Merged

AThousandShips force-pushed the doc_hierarchy branch from ae34661 to 17b848e Compare January 7, 2024 17:05

YuriSizov reviewed Jan 16, 2024

View reviewed changes

editor/doc_tools.cpp Outdated Show resolved Hide resolved

AThousandShips force-pushed the doc_hierarchy branch from 17b848e to 62f2556 Compare January 16, 2024 13:14

YuriSizov approved these changes Jan 16, 2024

View reviewed changes

editor/editor_help.cpp Outdated Show resolved Hide resolved

editor/editor_help_search.cpp Outdated Show resolved Hide resolved

Add inheriting classes to DocTools

dc86483

AThousandShips force-pushed the doc_hierarchy branch from 62f2556 to dc86483 Compare January 16, 2024 13:43

akien-mga merged commit 107f296 into godotengine:master Jan 16, 2024
15 checks passed

AThousandShips deleted the doc_hierarchy branch January 16, 2024 15:48

YuriSizov mentioned this pull request Jan 22, 2024

Open button gets disabled for some help classes when searching #87472

Closed

This was referenced Feb 6, 2024

Documentation: @GDScript and @GlobalScope are at the bottom of the list #63799

Closed

Fix @GlobalScope and @GDScript at the bottom of the list #65237

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add inheriting classes to `DocTools` #77554

Add inheriting classes to `DocTools` #77554

AThousandShips commented May 27, 2023 •

edited

Loading

YuriSizov commented May 29, 2023

AThousandShips commented May 29, 2023 •

edited

Loading

AThousandShips commented May 29, 2023 •

edited

Loading

YuriSizov commented May 29, 2023

AThousandShips commented Jul 13, 2023

AThousandShips commented Jul 13, 2023 •

edited

Loading

akien-mga commented Sep 8, 2023

AThousandShips commented Sep 8, 2023

akien-mga commented Sep 8, 2023

AThousandShips commented Sep 8, 2023 •

edited

Loading

AThousandShips Sep 8, 2023

YuriSizov left a comment

AThousandShips commented Jan 16, 2024

akien-mga commented Jan 16, 2024

AThousandShips commented Jan 16, 2024

Add inheriting classes to DocTools #77554

Add inheriting classes to DocTools #77554

Conversation

AThousandShips commented May 27, 2023 • edited Loading

YuriSizov commented May 29, 2023

AThousandShips commented May 29, 2023 • edited Loading

AThousandShips commented May 29, 2023 • edited Loading

YuriSizov commented May 29, 2023

AThousandShips commented Jul 13, 2023

AThousandShips commented Jul 13, 2023 • edited Loading

akien-mga commented Sep 8, 2023

AThousandShips commented Sep 8, 2023

akien-mga commented Sep 8, 2023

AThousandShips commented Sep 8, 2023 • edited Loading

AThousandShips Sep 8, 2023

Choose a reason for hiding this comment

YuriSizov left a comment

Choose a reason for hiding this comment

AThousandShips commented Jan 16, 2024

akien-mga commented Jan 16, 2024

AThousandShips commented Jan 16, 2024

Add inheriting classes to `DocTools` #77554

Add inheriting classes to `DocTools` #77554

AThousandShips commented May 27, 2023 •

edited

Loading

AThousandShips commented May 29, 2023 •

edited

Loading

AThousandShips commented May 29, 2023 •

edited

Loading

AThousandShips commented Jul 13, 2023 •

edited

Loading

AThousandShips commented Sep 8, 2023 •

edited

Loading