Add search keywords to the class reference #78990

RedMser · 2023-07-03T16:21:42Z

Fixes godotengine/godot-proposals#5085

Allows for finding methods, properties, signals, constants, theme items and annotations more easily.

Allow "keywords" attribute in aforementioned locations in the class reference XMLs.
Extends doctool, to preserve these attributes.
Update the XSD schema for the class reference.
Update the RST generator to include a meta tag for class keywords.
Update editor help search to allow filtering for these keywords.
Add some exemplary keywords attributes in the class reference, but more can be added in future PRs. They are merely included to not be forgotten in the proposal, and to be able to test the feature.

Ideas and Future

Should it be possible to add a @keywords ... comment in GDScript to define keywords for script classes and members? Implementation would look like GDScript: Add @deprecated and @experimental doc comment tags #78941
Idea for the future: add keyword search to GDScript autocompletion
Idea for the future: add keyword search to the "create new node/resource" dialog
Render the keywords list in a few places, such as
- Next to a matching search result (so you know why this result is showing)
- In the documentation (both RST and in the editor), to get a full list of related keywords

editor/editor_help_search.cpp

YuriSizov · 2023-07-03T16:34:18Z

Update editor help search with a toggle button to allow filtering for these keywords.

What's the use case for not wanting to search by keywords?

RedMser · 2023-07-03T16:38:56Z

What's the use case for not wanting to search by keywords?

Right now, the keywords do not show up anywhere in the UI, so I'm not sure if power users are gonna be happy that seemingly unrelated results suddenly show up in the search results.

If I had more time to work on this PR, I'd show the keyword that matched next to the search result, with greyed out text. Might take me a bit before I can get that implemented.

But I'm fine with taking the button out if there's no apparent need for it.

YuriSizov · 2023-07-03T16:43:58Z

I'm not sure if power users are gonna be happy that seemingly unrelated results suddenly show up in the search results

Well the point of having keywords would be to make sure we show more related results than we do now. Hiding them behind a toggle makes them harder to access and less useful.

RedMser · 2023-07-05T12:02:52Z

Removed the toggle so keyword searching is always enabled now.

Calinou

Tested locally, it works. Code looks good to me.

There's a small usability issue however:

When you search for a node directly, it's automatically focused:

When you search for a keyword, the node that matches the keyword isn't automatically selected:

Getting this working is important to reduce the number of keystrokes you need to open the documentation page, so I suggest looking into this if possible.

RedMser · 2023-07-05T14:57:23Z

@Calinou Done! Updated _match_item and calling it for each keyword.

~~Though entering kill will make it prefer Node.queue_free over e.g. Tween.kill, not sure if I should leave it like that or reduce the weight of keyword matches.~~

YuriSizov · 2023-07-05T16:09:02Z

Reducing the weight makes sense, as it's an indirect match.

akien-mga · 2023-07-10T08:02:58Z

I'm not too fond of having keywords as XML tag attributes.

Attributes are usually things generated from the codebase, and human-written content should be filled within tags (e.g. <description>Human written</description>).

So it might make more sense IMO to add an optional <keywords> tag, like we do with <link> for the <tutorials> section.

RedMser · 2023-07-10T10:40:36Z

So it might make more sense IMO to add an optional <keywords> tag

@akien-mga While I agree with your reasoning, it seems like it would have to be a breaking XSD schema change.
<member>, <constant> and <theme_item> are tags that only have a string content, so all of their descriptions would have to be moved into a <description> element.

Maintaining a backwards compatible parser sounds problematic (especially now that the version attribute is gone) and it would make new documentation features hard to discover.
Going through with the breaking change would (besides a large diff) break doctools of user-maintained modules, which might not be too bad?

Let me know what you think!

akien-mga · 2023-07-10T10:51:05Z

I don't understand, how would <keywords>3d, spatial</keywords> differ from the existing optional <link>https://example.com</link> tag?

Edit: Oh nevermind, re-read and checked the link, I see the problem. Hm...

I guess using an attribute is the least bad solution then.

Calinou

Tested locally (rebased on top of master 57919be), it works as expected with correct focus behavior now.

I can do a pass over the class reference to add keywords once this PR is merged.

Mickeon · 2024-01-24T16:56:25Z

Would be nice to address the conflicts. Reception on this seems fairly positive. Although the current implementation seems out of reach for translators, if that was ever a concern.

RedMser · 2024-01-24T17:29:21Z

Rebased onto latest master. Thanks for letting me know! ^^

Although the current implementation seems out of reach for translators, if that was ever a concern.

Since the API is not translated (so method names, property names, etc.), I don't think it matters. You wouldn't search for a Spanish keyword when all the possible results are only ever in English.

Mickeon

Took a deep look. You can get a lot of mileage out of this feature in the future.

It is kind of confusing to get search results from terms that are not directly visible, although that can be figured out later.

Calinou · 2024-02-05T19:18:12Z

Note for the future: Vector2/3's limit_length could have a truncate keyword as mentioned in godotengine/godot-proposals#9020.

AThousandShips

Looks good otherwise

editor/editor_help_search.cpp

akien-mga · 2024-02-09T16:52:47Z

It is kind of confusing to get search results from terms that are not directly visible, although that can be figured out later.

Yeah that's my main concern with the current implementation. I'd like to see something that makes it obvious to the user why the filtered entry matches their search. There could e.g. be a "(keyword: ragdoll)" added after the node name in the list, in the OP's example.

It shouldn't necessarily be blocking for this PR though, it could be worked on in a follow-up, possibly by someone else if wanted.

Allows for finding methods, properties, signals, constants, theme items and annotations more easily. - Allow "keywords" attribute in aforementioned locations in the class reference XMLs - Extends doctool, to preserve these attributes - Update the XSD schema for the class reference - Update the RST generator to include a meta tag for class keywords - Update the editor help to support filtering by keywords

More should be added in future PRs, wherever there is demand.

akien-mga · 2024-02-12T12:51:01Z

Thanks!

RedMser requested review from a team as code owners July 3, 2023 16:21

RedMser force-pushed the class-reference-keywords branch from 38cf495 to 4747fe9 Compare July 3, 2023 16:23

Calinou added enhancement topic:editor documentation usability labels Jul 3, 2023

Calinou added this to the 4.x milestone Jul 3, 2023

RedMser commented Jul 3, 2023

View reviewed changes

editor/editor_help_search.cpp Outdated Show resolved Hide resolved

RedMser force-pushed the class-reference-keywords branch 2 times, most recently from a42398d to 643c2e2 Compare July 3, 2023 16:33

RedMser force-pushed the class-reference-keywords branch from 92497d4 to 325c8a7 Compare July 5, 2023 12:02

Calinou approved these changes Jul 5, 2023

View reviewed changes

RedMser force-pushed the class-reference-keywords branch from 325c8a7 to aaf7ee9 Compare July 5, 2023 14:56

RedMser force-pushed the class-reference-keywords branch 3 times, most recently from 660771a to 5f97bb1 Compare July 8, 2023 15:41

Calinou approved these changes Jul 18, 2023

View reviewed changes

akien-mga self-requested a review August 2, 2023 08:56

YuriSizov modified the milestones: 4.x, 4.2 Aug 4, 2023

RedMser mentioned this pull request Sep 26, 2023

Support string.size() alongside string.length() godotengine/godot-proposals#7869

Open

YuriSizov modified the milestones: 4.2, 4.3 Oct 2, 2023

AThousandShips added topic:editor and removed topic:editor labels Nov 10, 2023

RedMser force-pushed the class-reference-keywords branch from 5f97bb1 to f0f60c6 Compare January 24, 2024 17:29

YuriSizov self-requested a review January 24, 2024 18:22

Mickeon approved these changes Jan 28, 2024

View reviewed changes

Calinou mentioned this pull request Feb 5, 2024

Add screen-related attributes to mouse input events #82800

Merged

AThousandShips approved these changes Feb 9, 2024

View reviewed changes

editor/editor_help_search.cpp Outdated Show resolved Hide resolved

editor/editor_help_search.cpp Outdated Show resolved Hide resolved

editor/editor_help_search.cpp Outdated Show resolved Hide resolved

editor/editor_help_search.cpp Outdated Show resolved Hide resolved

RedMser added 2 commits February 9, 2024 18:13

Update class reference to include some keywords

5911a12

More should be added in future PRs, wherever there is demand.

RedMser force-pushed the class-reference-keywords branch from f0f60c6 to 5911a12 Compare February 9, 2024 17:13

akien-mga merged commit 62fcc7e into godotengine:master Feb 12, 2024
16 checks passed

Calinou mentioned this pull request Feb 21, 2024

Add keywords to improve search in the class reference #88641

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add search keywords to the class reference #78990

Add search keywords to the class reference #78990

RedMser commented Jul 3, 2023 •

edited

Loading

YuriSizov commented Jul 3, 2023

RedMser commented Jul 3, 2023

YuriSizov commented Jul 3, 2023

RedMser commented Jul 5, 2023

Calinou left a comment •

edited

Loading

RedMser commented Jul 5, 2023 •

edited

Loading

YuriSizov commented Jul 5, 2023

akien-mga commented Jul 10, 2023

RedMser commented Jul 10, 2023

akien-mga commented Jul 10, 2023 •

edited

Loading

Calinou left a comment •

edited

Loading

Mickeon commented Jan 24, 2024

RedMser commented Jan 24, 2024

Mickeon left a comment •

edited

Loading

Calinou commented Feb 5, 2024 •

edited

Loading

AThousandShips left a comment

akien-mga commented Feb 9, 2024 •

edited

Loading

akien-mga commented Feb 12, 2024

Add search keywords to the class reference #78990

Add search keywords to the class reference #78990

Conversation

RedMser commented Jul 3, 2023 • edited Loading

Ideas and Future

YuriSizov commented Jul 3, 2023

RedMser commented Jul 3, 2023

YuriSizov commented Jul 3, 2023

RedMser commented Jul 5, 2023

Calinou left a comment • edited Loading

Choose a reason for hiding this comment

RedMser commented Jul 5, 2023 • edited Loading

YuriSizov commented Jul 5, 2023

akien-mga commented Jul 10, 2023

RedMser commented Jul 10, 2023

akien-mga commented Jul 10, 2023 • edited Loading

Calinou left a comment • edited Loading

Choose a reason for hiding this comment

Mickeon commented Jan 24, 2024

RedMser commented Jan 24, 2024

Mickeon left a comment • edited Loading

Choose a reason for hiding this comment

Calinou commented Feb 5, 2024 • edited Loading

AThousandShips left a comment

Choose a reason for hiding this comment

akien-mga commented Feb 9, 2024 • edited Loading

akien-mga commented Feb 12, 2024

RedMser commented Jul 3, 2023 •

edited

Loading

Calinou left a comment •

edited

Loading

RedMser commented Jul 5, 2023 •

edited

Loading

akien-mga commented Jul 10, 2023 •

edited

Loading

Calinou left a comment •

edited

Loading

Mickeon left a comment •

edited

Loading

Calinou commented Feb 5, 2024 •

edited

Loading

akien-mga commented Feb 9, 2024 •

edited

Loading