Improve search in web documentation

[anniryynanen]

Describe the project you are working on

Small game projects and a pixel drawing app.

Describe the problem or limitation you are having in your project

Finding things in the online documentation has been difficult for me because the search functionality is so limited. I often have to resort to external search engines to find if something has built-in support or not. Even finding things I already know exist is difficult; searching for "CharacterBody" doesn't find "CharacterBody2D".

With the current state of the search I feel bad directing people to look for answers in the docs, when I myself have a hard time doing it.

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

My current idea is to use Sphinx's Web Support. If I've understood things correctly, it builds search indexes when the docs are built. I haven't tried it yet but it sounds like it could be a big improvement.

I'm not sure if it's the best way, I'd love to hear if anyone has other suggestions. If this proposal is accepted I can implement it.

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

I would add the sphinxcontrib.websupport extension and set it up in conf.py. Then add Python functionality under _extensions to use Web Support when the search is used. I haven't worked with Sphinx before, but I'm guessing that's how it'd go.

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

No.

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

This is about the docs website, not really about the engine. I'm not sure if the proposals repository is used for the website too but I thought this one might warrant it. Either way, it's big enough that I feel like I need feedback before I start implementing it.

[Calinou]

We tried Algolia search a while ago, but it wasn't that much better than the built-in docs search so we ended up removing it.

Note that Godot docs are on Read the Docs, so we need to abide by what they allow on their platform. Extensions that require hosting a dynamic backend probably won't work.

That said, I don't think this is what Sphinx's web support achieves. That extension is meant to integrate a Sphinx website into a dynamic Python-based website, not improve Sphinx's built-in search by building an index (which Sphinx already does anyway).

[anniryynanen]

Interesting. I'll keep looking, maybe I can find other alternatives.

[anniryynanen]

I'm guessing the docs are hooked to Read the Docs' server side search. They advertise support for fuzziness in https://docs.readthedocs.io/en/stable/server-side-search/syntax.html#special-queries; in theory you could for example write "CharacterBody~2". But in Godot docs that returns results for "2" and in https://readthedocs.org/search/ which searches all of Read the Docs including Godot I get this beautiful whale:

          .
         ":"
       ___:____     |"\/"|
     ,'        `.    \  /
     |  O        \___/  |
   ~^~^~^~^~^~^~^~^~^~^~^~^~

   Fail.  Check back in a bit!

Still, if that fuzzy search worked it could maybe be added to all search terms, or at least we could tell people they can use it.

[marcotrosi]

Hello, coming from a duplicate issue https://github.com/godotengine/godot-docs/issues/10278 I just want to repeat what I wrote there ...

---

Hello Team Godot,

we again had the issue in our Godot group that we wanted to help a user, but the search engine of the Godot documentation site makes it sometimes hard for us to quickly find what we need.

For example I just wanted to find the documentation for the lerp function, it shows all kinds of things but not the documentation for that function.

I would expect that the first three entries are ...

• https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-method-lerp
• https://docs.godotengine.org/en/stable/classes/class_vector2.html#class-vector2-method-lerp
• https://docs.godotengine.org/en/stable/classes/class_vector3.html#class-vector3-method-lerp

or that there is a function reference with all functions only, so that we can use the browser search

or that the search can be made more precise, like "func: lerp"

or that each occurrence of the word "lerp" in the code examples would be a link to the documentation of the used function.

anything is fine, but as it is today it's not okay, the search is currently not practical.

Thank you very much

keep up the great work, sending love

--marco