Make sphinx search embeddable in other websites

[slackner]

Is your feature request related to a problem? Please describe.

I'm using sphinx to create an extensive documentation for a web application. To help users find the right article more quickly, I would now like to link to the documentation from the app. Of course, this is possible with static links, but it is very difficult to maintain in the long run, because the links always have to be adjusted manually when changes or additions are made to the documentation. It would be nicer if Sphinx would offer the possibility to integrate its search into external websites.

Describe the solution you'd like

I would like to be able to embed searchtools.js and documentation_options.js into other websites, and have an API call e.g.Search.search that performs a search and returns the search result (e.g., as a JS promise, or via a callback function). These functions should not do any DOM manipulations and have a stable API interface.

Describe alternatives you've considered

• I've considered embedding the JavaScript libraries directly into the app. However, it is problematic that they react to query parameters, contain hardcoded element identifiers, and do DOM manpulations.
• I've considered re-implementing searchtools.js in my own project. However, this means that it will no longer work when Sphinx changes the searchindex.js file format or scoring computation. Also, the stemmers would still have to loaded from Sphinx if I don't want to reimplement them aswell.
• I've considered embedding the search via an iframe. In this case the main challenge is making it look nice within the application.
• I've considered pre-computing the search results during the build process of the web app, but haven't found a nice way to do that using the Sphinx Python API.

[AA-Turner]

Have you looked at 'sphinxcontrib-websupport'? It may have functionality to help.

A

[tk0miya]

websupport is not good for this case. It's a framework to embed Sphinx documents into the web apps. But this case is embedding search feature to the external websites. So it would be nice if we can separate search core feature from our search engines to build a custom JS application.

I'm not good at JS and search feature. So PR is welcome :-)

[TimKam]

You should be able to trigger a search using searchtools.js and the searchindex.js file that is created when your project is built. With this, you can get a working search. However, there are some challenges:

1. You need to make sure that the 3rd party app always gets the updated searchindex.js file when the Sphinx-generated documentation page is updated.
2. To make use of the preview feature, you need to be able access the HTML files, so you either need to move a full copy of your project to the 3rd party app or to somehow enable the documentation page to serve them without running into issues with cross-domain security features.

In case there is a serious interest in this, one could write a brief tutorial based on the experiences of people who have actually deployed such a feature.