Allow Search Help to search in more places

[RedMser]

Describe the project you are working on

Godot Engine

Describe the problem or limitation you are having in your project

The Search Help dialog (shortcut F1) only allows searching through the Class Reference and provides documentation on this. But there are a lot more areas that could be documented from inside Godot itself, such as

• The GDScript language (list of keywords, data types, syntax, etc.)
• The Shading language (list of keywords, data types, built-in variables per context, etc.)
• Custom documentation for add-ons (how to install, getting started, high-level overview page that explains concepts, etc.)

and likely more. This requires the user to turn to other means, like using the online documentation search, or looking at documentation files shipped with the add-on they downloaded.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

This supersedes #3767 and #2361, as it explains a way on how to integrate these changes using a single solution.

The Search Help dialog should be extended with these additional documentation sources. Additionally, the documentation viewer must support viewing more than just class documentation files.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

Note that this mockup has some shortcomings and does not reflect the exact implementation goal. Some of these are elaborated upon in the following points.

Add multiple root nodes

Each category of documentation should be found within its own root node. This makes it clear what context the documentation comes from and where it is applicable.

Filter documentation categories

Using the same filtering system as in the scene tree, prefixing a search using a: g: s: c: will filter the results to only show that specific category's entries. Multiple prefixes can be used to search in multiple categories. Entering no category will search in all of them by default.

An alternative to this approach could be toggle buttons added to a 2nd row below the filter bar.

Context-aware

Starting a F1 search from inside the Shader Editor should already have the s: shader prefix in the filter bar, so only shader-related results are found. Similar would go for the Script Editor starting out with a: g: c: (everything except shader language).

As such contextual actions are frowned upon by some users, this behavior should be optional and be implemented as an editor setting (defaults to enabled).

How do we show this documentation?

Currently, the documentation pages themselves are rendered by looping over entries of a ClassDoc and writing a document into RichTextLabel. A similar approach can be used for the newly added documentation page types.

• Shading language and GDScript language: these two are .rst files, which could theoretically be parsed back into BBCode or directly loaded into a RichTextLabel. This would set the foundation to allow reading the entire engine's documentation in the editor as well, possibly allowing to search it. Another option could be to convert these files to another format first, using existing converter utilities.
• Custom documentation: this could be written as BBCode directly (proposed file extension .bb), and discovered in some way. For example, by searching the project recursively for these files (possibly only inside of a "docs" folder?), and then checking whether it belongs to the main project or to a given add-on. If we write a .rst file parser, then this type of documentation files would also be allowed.

If this enhancement will not be used often, can it be worked around with a few lines of script?

This is a core usability issue.

Is there a reason why this should be core and not an add-on in the asset library?

This is about extending the Search Help dialog, which is a core feature.

[YuriSizov]

This proposal currently doesn't cover the most important part: where would we get this documentation from?

Online docs are independent and don't have a search index compatible with the idea. So we would have to maintain all these docs with the engine somehow. This is what should be discussed first. The search itself would be a trivial addition on top.

[RedMser]

@YuriSizov One possible solution is proposed under "How do we show this documentation?" which would allow viewing the entire manual in the editor. Though it does not elaborate on having to build the search index from this data (e.g. headlines from the gdscript reference).

[YuriSizov]

Online documentation is not written in a way that would suit this kind of search. It would be very difficult to maintain. Not to mention having this bidirectional relationship between the two projects is a problem in and of itself.

[dalexeev]

• See also #4285.