Search ranking seemingly has no effect

[astrojuanlu]

Details

• Read the Docs project URL: https://readthedocs.org/projects/kedro/

Expected Result

In kedro-org/kedro#3546 we added this to .readthedocs.yml:

search:
  ranking:
    # Match API docs (files prefixed "kedro.") and push them down the ranking
    '*/kedro.*.html': -5

with the intention of having narrative docs show above API pages for search.

Actual Result

We still see API results on top.

See for example searching for "node":

in https://docs.kedro.org/en/latest/

• Should we have marked this as -10 to drop it right down?
• Should we also boost the narrative docs up?
• Should we even expect to see results right now, or is the indexing done separately to the HTML build? How can I force a new index?

cc @stichbury

[humitos]

    '*/kedro.*.html': -5

This particular case that uses two * called my attention and I went to the docs to check if it's possible. At first sight, it doesn't say it's not allowed and I understand that's valid (https://docs.readthedocs.io/en/stable/config-file/v2.html#search-ranking)

I think you did everything correctly and it should work as expected. The build for latest version already includes the search.ranking configuration properly (https://beta.readthedocs.org/projects/kedro/builds/23208343/), which tells the search engine to create the index with that particular ranking at build time.

I'd say there are two alternatives here:

1. we are interpreting the docs incorrectly and multiple * are not allowed
2. there is a bug when creating the search index

cc @stsewd do you know what's happening here?

[stsewd]

Hi, the file you are trying to match is kedro.framework.hooks.specs.DatasetSpecs.html? We do the match over the path starting from the root, so */ is trying to match a directory first, but that file is at the root, so it doesn't match. The pattern you need is kedro.*.html, if you have more files like that in subdirectories, then */kedro.*.html is also needed.

[stsewd]

We should probably update this example to make it more explicit about matching subdirectories only.

https://docs.readthedocs.io/en/stable/config-file/v2.html#search-ranking

    # Match all files that end with tutorial.html
    '*/tutorial.html': 3

[astrojuanlu]

Thanks for your answers! We're moving some docs around to make it easier and will give this another go.

If we put our API docs under /api, would api/*: -5 be a good rule?

[stichbury]

Indeed, thanks for your help! Just to clarify, I put the ranking down to -5 rather than -10 because I didn't want to hide the docs behind everything else that matches the search term, but wanted to force the markdown "narrative" docs in front (on the whole) where they're a better match. Does that sound about right?

[stsewd]

If we put our API docs under /api, would api/*: -5 be a good rule?

Yes

Indeed, thanks for your help! Just to clarify, I put the ranking down to -5 rather than -10 because I didn't want to hide the docs behind everything else that matches the search term, but wanted to force the markdown "narrative" docs in front (on the whole) where they're a better match. Does that sound about right?

yes

[astrojuanlu]

FTR, we made the changes we described and things seem to be working now, thanks for the support!