Docs: Search feature improvements

[anden-akkio]

Summary

My organization is considering a FastAPI -> Litestar migration and one of the things that stands out to us is the search feature on the docs, which seems iffy at best. The docs are nice, and I like that there's two distinct types ("example-driven" docs + "api" docs) but it still feels like subpar DX.

• It seems very literal and substring-based. Something fuzzier (like you'd get by using some kind of in-memory semantic search or even a full solution driven by Elasticsearch or similar) that potentially also factors in page content and not just title (if not already done) would likely be better.
• Having suggestions pop up as you type (potentially debounced, if intensive) would shorten the loop, rather than requiring users to hit Enter and then look through that list.
• Being able to easily distinguish "example-driven" and "api" docs would be nice. Adding a subheader or something below each search result would probably do the trick.

Using Google with site:litestar.dev is also a consideration, but I think due to you guys presumably recently moving the website due to the rename, Google hasn't really indexed huge chunks of it yet, so that's not really that useful.

[provinzkraut]

This is unfortunately a limitation of Sphinx. The search it provides is not great (as you've noticed), and adding a new search to it isn't actually all that trivial. FastAPI uses mkdocs, which in turn uses lunr.js for the search.

Mkdocs, and more specifically, Material for MkDoc adds a ton of features to make the search as great as it is, so it's not as trivial as just adding lunr.js to Sphinx somehow.

I do agree however that this is something that would be really great to have. I had already started some experimentation with adding something, but my time is limited an this somehow got lost.

If anyone is willing to contribute towards this, it would be very welcome though and I'd be happy to give some pointers where/how this might be done.

[haffm]

Is the preferred solution to improve search with the existing Sphinx docs or move to Mkdocs/something else?

[provinzkraut]

We will stay with Sphinx for the docs. Mkdocs is nice but it really only has one theme you kinda have to use if you want all the features and its API documentation is subpar compared to what Sphinx has to offer. We originally had our docs in Mkdocs and specifically migrated to Sphinx because of this.

So the solution would be to improve the search for the existing docs.

[ADV1K]

I know it's a hard ask, but could we use the sphinxawesome theme instead of maintaining our own theme?
It has inbuilt integration with algolia.

[JacobCoffee]

This can be closed as 3.0 documentation will ship with Shibuya's sphinx-docsearch integration