[DOCS]: Improve Search Experience [ONGOING]

[AstreaTSS]

Page

https://interactions-py.github.io/interactions.py/

Problem description

Note: the purpose of this issue is to essentially say "yeah, we know the search on the docs sucks, here's why it can't be magically improved." We don't want to seem like we're purposefully ignoring its awfulness, but our hands are tied, and I want to use this issue to explain why.

Let's face it: the search for the documentation is... not great at all. Really, the simplest way of confirming this is to search for "member", a search that should easily go to the member section of the user page, but instead gets caught up by MODEL_TO_CONVERTER and other random files.

Work has been done to make the experience slightly better, like with #1576 (to the point where searching up "slash command" leads to the proper guide as the first result), but we haven't really been able to make huge progress with this.

There's a pretty simple reason why: we're being blocked by mkdocs-material, the documentation framework that generates our documentation website. While Material has otherwise been pretty decent once quirks were worked out, they've admitted that documentation search is poor. I suggest reading over that issue if you're interested - it explains quite a bit about why it sucks and steps being taken to improve search.

In short: it's not a simple problem, and their solution is to completely remake the search functionality, which needless to say, takes time. They've been making good progress too; using their search preview branch makes it so "member" has the correct result in the second entry (which is good enough for most people, I'd imagine), amongst other improvements. That being said, it's unstable, and so obviously we can't use it yet.

We also can't really work around these issues ourselves due to the complexity of search and how it isn't really meant to be customized that much in its current form, something which they noted they wanted to fix. As such, we're unfortunately stuck with what we have now.

Why not switch to Sphinx?

Any of you savvy enough in the Python sphere know that many Python libraries use Sphinx over MkDocs - they both are able to generate documentation websites, so it's a matter of personal preferences and usecases. It also tends to have a better search, at least for API references, and was used for v4.

However, we can't just switch to it like that:

• Switching over from MkDocs Material to Sphinx would require a massive amount of works, as many features that are exclusive to MkDocs Material would have to be changed to their Sphinx equivalents. My own experimenting revealed massive hurdles in even getting things to run under Sphinx - fixing every mistake on top of that is no doubt grueling.
• It... doesn't actually improve search by that much, at least for interactions.py v5 specifically. From the same experimenting, while "member" did produce a sane result, "slash command" was so utterly wrong because Sphinx could not handle guide page searching well, resulting in "junk" pages.
• Sphinx's closest parallel to our current theme, sphinx-immaterial, is nowhere as fully featured as what we have right now.

Suggested changes

Again, the best solution is https://github.com/squidfunk/mkdocs-material/issues/6307, which relies on mkdocs-material to get it done. Please give them patience and don't annoy them over the issue - they're aware of what needs to be done thanks to the thousands of other sites using it anyways.

Till then, we wait.

Additional context

If you're curious, you should try out the docs with https://github.com/squidfunk/mkdocs-material/pull/6372 - the results you get are pretty good.

[squidfunk]

Author of Material for MkDocs here. Thanks for your kind words and patience! I'm absolutely sure it will be worth it ☺️

[eightween]

Elevating issue