templates: add cross-project search using ReadTheDocs API - #319
Conversation
Problem: The sphinx_immaterial theme uses client-side search that only searches the local project's searchindex.js file. Even though flux-docs and its subprojects (flux-core, flux-sched, flux-security, flux-rfc) are configured in ReadTheDocs as a project family, users cannot search across all documentation from the main site. Solution: Override sphinx_immaterial's partials/search.html template to use ReadTheDocs' server-side search API with the subprojects=true parameter when on RTD (falls back to standard theme search for local builds). Use the relative API endpoint (/_/api/v3/search/) to avoid CORS issues. Add on_rtd to html_context in conf.py so it's available in templates. The custom search queries all configured subprojects and displays results with project labels (e.g., [core], [sched]). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
Ok, that didn't quite work. I'll be iterating here until it works. |
82d5de3 to
03da0e0
Compare
|
Ok, the changes "work" but we can't test the cross-site search functionality until this is merged. |
garlick
left a comment
garlick
left a comment
There was a problem hiding this comment.
Well let's give it a try then!
Merge Queue Status
This pull request spent 8 seconds in the queue, including 1 second running CI. Required conditions to merge
|
|
Didn't seem to work 😞 I'll keep poking at it. It seems to use the right request to readthedocs so maybe something is not configured correctly there. |
|
It is the Django REST Framework. So you can likely just use: https://app.readthedocs.org/api/v3/ I'm not sure we can assume that the API is being served from the node where the static site lives (did an LLM suggest that?) It's not a design that makes a lot of sense, unless readthedocs is a monolithic architecture. My suggestion is to use the above to get the exposed API. It will work for development too. And you can find the source code here: https://github.com/readthedocs/readthedocs.org/blob/603b87bbd69071a8ad80b16c9f09543da24b6ff0/readthedocs/search/api/v3/views.py#L168 Django (and Django REST) is really great! It was always my choice for APIs. |
|
But hold the phone - are you sure the "not working" isn't a lab thing? It looks like it's working here! 🎉 
Landing page looks great, by the way! |
3 participants
Problem: The sphinx_immaterial theme uses client-side search that only searches the local project's searchindex.js file. Even though flux-docs and its subprojects (flux-core, flux-sched, flux-security, flux-rfc) are configured in ReadTheDocs as a project family, users cannot search across all documentation from the main site.
Solution: Override sphinx_immaterial's partials/search.html template to use ReadTheDocs' server-side search API with the subprojects=true parameter when on RTD (falls back to standard theme search for local builds). Add on_rtd to html_context in conf.py so it's available in templates. The custom search queries all configured subprojects and displays results with project labels (e.g., [core], [sched]).
The only way to check if this works is to let RTD build this PR and check if search is working in the preview.