godotengine / godot-docs

Godot Engine official documentation
https://docs.godotengine.org
Other
3.93k stars 3.21k forks source link

Improve search in web documentation #9646

Open anniryynanen opened 3 months ago

anniryynanen commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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

anniryynanen commented 3 months ago

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.