Use API V3

[stsewd]

• Added 2 new options: rtd_sphinx_search_default_filter and rtd_sphinx_search_filters.
• The options are passed as a JSON object to be read by our JS code.
• The default filter defaults to the current project and version (extracted from the RTD env vars)
• Filters are implemented as check boxes, we only support one filter at a time (when a filter is selected, we uncheck all others)

How to test locally:

• Run your local version of RTD
• To allow cross site requests, add |/api/v3/search at https://github.com/readthedocs/readthedocs.org/blob/b574f4b0dad34ccba8595cee72246d3473f8a2e5/readthedocs/settings/base.py#L769-L781
• Change the rtd_dummy_data.json file
  • 'proxied_api_host': 'http://devthedocs.org'
  • Set the project and version to a project that you have locally
• Change the value of rtd_sphinx_search_default_filter = "project:superproject/latest" to the slug of a project you have locally
• Build the docs:

cd docs
make clean html

• Open the _build/index.html file.

showcase

showcase.webm

Closes https://github.com/readthedocs/readthedocs-sphinx-search/issues/129 Closes https://github.com/readthedocs/readthedocs-sphinx-search/issues/130 Closes https://github.com/readthedocs/readthedocs-sphinx-search/issues/131

[humitos]

I haven't tested this, but I just skimmed the code thinking about https://github.com/readthedocs/readthedocs.org/pull/10127 and how we are going to integrate it there. It seems that the only relevant change is the addition of two new configs. We can get those from the user (.readthedocs.yaml) or the doctool itself (readthedocs-build.yaml). I think it looks good and we will be able to integrate it properly 👍🏼

Filters are implemented as check boxes, we only support one filter at a time (when a filter is selected, we uncheck all others)

Instead of using check boxes, I'd say we should use radio buttons then, which provide this UX natively.

[stsewd]

Instead of using check boxes, I'd say we should use radio buttons then, which provide this UX natively.

Radio buttons don't allow you to uncheck them.

[stsewd]

are there specific things you want to double-check before merging?

Well, I need to fix the test :D, but wanted a review first, before dealing with selenium

[ericholscher]

I'm 👍 on shipping this, since it's not super heavily used, if it's been reviewed. I think user feedback will be the main thing that we care about. I agree this is a really exciting addition, so let's ship it and get it running on our docs, and then we'll get lots more feedback I imagine :)

If the tests are super brittle or annoying, we can also discuss changing them up in some fashion. I don't have a ton of context about how complex they are, but I feel like selenium is probably overkill, and we could be using some lighter weight JS test stuff? Though again, I don't have much knowledge there..

[stsewd]

If the tests are super brittle or annoying, we can also discuss changing them up in some fashion. I don't have a ton of context about how complex they are, but I feel like selenium is probably overkill, and we could be using some lighter weight JS test stuff? Though again, I don't have much knowledge there..

Yeah, I'd prefer more unit tests here at the js level. But we do have some UI logic that selenium helps to test, but also, it's small, so it isn't hard to manually test that.

[humitos]

Cool! Since only tests were left here, I started using the .js file from this repository in the new client. See https://github.com/readthedocs/readthedocs-client/issues/19. I had to modify some part of it to allow me to move forward with the new integration. However, I don't think that's a problem since it's already using the APIv3 backend -- which is the work done in this PR.