Search: API V3

[stsewd]

Implementation of #9533

Fixes #9573

This is on top of #9624

At first, I started to find a way to share most of the code with API v2, but the code resulted hard to follow,
so I just did a clean start for the new API (well, almost, there are still a lot of things that are being re-used).

• The new syntax can be used in the global search
• The project search now redirects to the global search with the current project set in the query.
• Some facets have been removed to just support the project/language facets.
• The global search now defaults to type=file.
• You can still search projects.
• The project facet isn't used directly, but only to aggregate results in the dashboard.
• The documentation was re-organized into a new directory instead of just one page.
• The advanced search guide was deleted, and their contents are now part of the documentation itself.

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--9625.org.readthedocs.build/en/9625/

• Developer's documentation (dev): https://dev--9625.org.readthedocs.build/en/9625/

[stsewd]

This should be ready, but we should first merge #9624, so I can fix the merge conflicts :/

[ericholscher]

@stsewd This feels close. You mentioned some width issues w/ the search box, do you have a link to a good screenshot of that?

[stsewd]

@ericholscher sorry, I thought I've attached screenshots in the PR description, looks like I didn't.

Basically, the text hides behind the "Search" button, and it also takes a lot of space that would be welcome when searching more than one project. We should probably just replace it with an icon and have the search bar not overlap with the button (not sure how this implemented in the new templates)

[ericholscher]

Yea, 👍 on either hiding the search box, or just moving it down to a new line.

[humitos]

I started doing a review but I noticed that it will take more time than I thought. It seems to be a big project. I'll come back to it with more time and focus.

[humitos]

Why not creating a proper serializer for each of them instead of methods?

Example of this from APIv3

readthedocs.org/readthedocs/api/v3/serializers.py

Line 261 in 8ccd55c

urls = VersionURLsSerializer(source='*')

[stsewd]

The only one we can do this for is for the version, for the project we need to call get_project_alias to get the alias. The objects these serializers deal with are ES result objects, not RTD objects, we don't have that field in the ES object.

[stsewd]

@ericholscher I'm trying to fix the search bar, but looks like we are using it in other places as well (the same structure/css classes).

Current state

My small fix

Looks like the problem is with the width being hardcoded (width: 513px;)

readthedocs.org/media/css/core.css

Line 375 in 5e870d4

.wide-search-bar input[type="text"] { border-top-left-radius: 3px; border-bottom-left-radius: 3px; -moz-border-radius-topleft: 3px; -moz-border-radius-bottomleft: 3px; -webkit-border-top-left-radius: 3px; -webkit-border-bottom-left-radius: 3px; width: 513px; }

So I tried to fix it setting the width to width: 100%;

The overlap is reduced, but now all forms have that small overlap.

Moving the button to a new line may require some more CSS...

New templates

The new templates won't/don't have this issue

If my small fix is enough, let me know. But I'm not sure if it's worth investing more time in that with the new templates coming 🤔

[ericholscher]

@stsewd I don't think we need to invest much time in this. It seems fine as is, as well. It's not broken, so definitely don't invest much time here.

[ericholscher]

@stsewd I'm pretty happy with where this PR is. Is there any backwards incompatible changes required here, or can we roll it out and roll it back if needed?

[stsewd]

@ericholscher

• The doc structure was changed (redirects are needed in place, cc @benjaoming in case any of this collides with the work of moving our docs to diataxis)
• most of the facets are removed (dashboard search)
• Old project search links will redirect to the global search

One small detail that you may have an opinion on #9533 (comment).

What's next?

• Use api v3 in our embedded js search
• Use api v3 in our sphinx search extension

[benjaoming]

@stsewd we added this PR to the "iteration 0" milestone of the Diátaxis changes, so right now, I would hope that it's fixed up before Iteration 1 👍

[stsewd]

so right now, I would hope that it's fixed up before Iteration 1

@benjaoming not sure what you mean with this p: should be fine to merge as is?

[benjaoming]

@stsewd

@benjaoming not sure what you mean with this p: should be fine to merge as is?

Yes absolutely, I wanted to clarify the below question

cc @benjaoming in case any of this collides with the work of moving our docs to diataxis

The answer is basically no, please merge, and that even resolves one of the items in the Diátaxis milestone 👍 🎉

[ericholscher]

Use api v3 in our embedded js search

@stsewd What is this exactly? The indoc search that isn't using our extension?

Use api v2 in our sphinx search extension

I don't fully understand why our extension would use v2 instead of v3?

[stsewd]

I don't fully understand why our extension would use v2 instead of v3?

opps, that was my mistake, I meant to say "Use api v3 in our sphinx search extension"

Use api v3 in our embedded js search

@stsewd What is this exactly? The indoc search that isn't using our extension?

yes

[benjaoming]

@stsewd I've added Fixes #9573

[ericholscher]

I think I'm OK merging this, and if I can get it tested on Monday that will be useful, but otherwise it feels safe to deploy. We can continue to iterate on it as we get real user feedback, but there's a bunch of improvements here that I'm excited about. 👍