Search related settings in the configuration file

[stsewd]

This is related to #7082

I think good candidates are settings that can be applied at build time and/or are attached to a version. Another way is to build a search UI with options to filter results.

I'm referring here to users (users who read/search the docs) and authors (users that have control over the project/docs).

Some settings we can have:

• Allow disabling sever side search (we currently have a flag for this), and we currently require rebuilding the docs in order for this setting to take effect (we have had some other ideas to allow us to disable server side search without rebuilding). So this setting could be in the config file.

• Allow ignoring files from being indexed. Since index is done at build time, this requires rebuilding the docs. This can be useful to have pages we don't want to show in search results, like the 404 or search page (this is useful when we index directly from html files Search: index from html files for mkdocs projects #7208). So, this makes sense to have in the config file. Done in Search: allow ignoring files from indexing #7308

• Allow boosting results from some pages. We often have a new version of an api or whatnot, and we want our users to start using that instead of the old one. I'm still reading, bug looks like we can do boosting at index time and query time. I don't see where else to put this information if not in the config file, so boosting at index time seems like what we want. So authors can set explicitly this. TODO: see what values we can allow: only positive numbers? Negative numbers? integers? floating numbers?
  Already done Search: custom search page ranking #7237

• Allow users to set from which subprojects and versions to include results from (or prefer default versions of the subprojects). Currently, a search in the main project will return search from all its subprojects. Maybe not all users want this behavior or maybe want to ignore some subprojects. We currently filter the subprojects at query time, so this can be easily into the UI (here the decision is done for the final user instead of the author). Note: we default to the default version of the subproject now, not sure if we still want this to be more customizable, but with the current code we can if we want.

• Fuzzy search and complex queries. We were doing always a complex query (allowing usage of some operators for having more precise results), but a query that doesn't make use of those operators can return poor results (we have implemented a feature flag for this at Search: improve results for simple queries #7194). That seems like a good default, but maybe we want to let users/authors decide which one to set? Or the level of default fuzziness? (currently in auto, that means it depends on how long the string is).

• Another settings?

Some examples of how this will look like are:

Disable SSS.

version: 2

search: false

Exclude from indexing

version: 2

search:
  exlude:
    - 404.html
    - search.html
    - search/index.html
    - allow-gloves/*

Boosting Already done in #7237 (ranking)

version: 2

search:
  boosting:
    - api/v1/*: -1
    - api/v2/*: 2

Don't include results from subprojects

version: 2

search:
  subprojects: false

Include results from some subprojects

version: 2

search:
  subprojects:
    - one
    - two

[agjohnson]

These are great suggestions! 💯

It might be worth breaking the remaining features down into issues so we can tackle a few more of these.

I've noted some additional syntax to project index configuration at #8678

[humitos]

There are some features that are already implemented. On the other hand, the remaining ones can be moved to the new "search addons" for a better UX, I'd say:

Allow disabling sever side search (we currently have a flag for this)

This is currently supported by enabling/disabling the "search addons". Since we won't be overriding the default search from the doctool anymore, I think disabling our "search addons" is enough. See

Allow users to set from which subprojects and versions to include results from (or prefer default versions of the subprojects)

This will be managed by the "search addons" with the customizable filters. Like, "Search only on this project", "Search on all subprojects", etc. See readthedocs/addons#29 and readthedocs/addons#22

Fuzzy search and complex queries

This has it's own issue at #10568 and it seems that we can get the same behavior by using <word>* when searching. Also see readthedocs/addons#33

I'm closing this issue, but feel free to reopen if you consider there are actionable here that are not tracked somewhere else.