Update the API to call our new API:

https://docs.readthedocs.io/en/stable/server-side-search/api.html#api-v3

This is likely bc of the shortcut feature, we should make it pass when the search dialog is already open

In #31 we added / as a hotfix to open the search box which is good.

Today I found that Stripe docs goes a step further here and uses CTRL+f which I thought immediately it was a bad decision because "I want to use just the regular search of my browser", but then I saw it says that you can hit CTRL+f again to switch to the default search feature 💯

NOTE the message and checkbox at the bottom right

You can try it by yourself at https://stripe.com/docs/api/events/types

Currently, travis is running tests for only chrome and firefox.
We want IE and MSEdge also.

Several small fixes have been merged since the last release, namely #83, #89, #93, and #94. In particular, I think #89 and #93 are good developer and user experience improvements. Is there a chance to cut a release?

When searching for a certain term, that term is displayed in the search bar.
When clicking the search bar, a search window pops up with a new empty search input.
The old search term is not in the input anymore.

This is annoying when the new search term is very similar to the old search term; for example when you made a typo in the old search term and you want to correct that.
There is no way to change the search term without completely re-entering the search term.

My prefered solution would be to show the old search term in the search input field by default.
Clearing the field manually is only a minimal effort.
If the text is selected then clearing it is usually only one keypress of any key except an arrow key.
Search inputs for all other websites that I know of work like this.

(original issue)

Searching is not a pleasant experience, and it's mainly because of a slow, (assumably) mobile-first search popup. While I can't speak for every documentation website, at least for the repository I'm working with (Godot Engine), desktop monitors should be the primary device to target for user experience. Example in the Godot Engine docs:

A better instant search would only take up a modest amount of space under the search bar, and not take away the ability to use the current page. This would likely imply different search UI on mobile and desktop devices.

Hi!

would you mind making a PyPI release for this (could even be an alpha/beta version, such as v0.1.0a1)?
Besides reserving the name, this would also make using the extension a bit easier in some contexts.

It would be very useful to have the ability to have a default search query that users get when they open. This would be configurable at the integration point for the extension, perhaps adding a config option:

rtd_sphinx_search_default_filters = 'subprojects:docs'

The use case here is:

• I am a project on RTD that has subprojects
• We want users to be able to search across all the subprojects easily
• When they launch search, it should already have subprojects:<slug> prepended to the search in some fashion

Currently, closing the search modal has got no animation.
It would be nice to have some (just like the opening of the modal has)

After enabling the sphinx_search.extension module, we've started to see the following warnings in our Sphinx logs:

WARNING: the sphinx_search.extension extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

WARNING: doing serial read

Looking at the Sphinx docs, it seems that Sphinx expects the extension metadata to specify whether it's safe to read / write files in parallel:

https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata

These warnings can get quite noisy in our CI/CD pipeline, so it would be great to your thoughts on whether this is something that can be added to this extension's metadata.

I've tried to make this work in a small test case. Everything I've tried has failed to load the extension.

I tried copying your conf.py and requirements.txt verbatim used in this repository. That didn't help. It failed on import sphinx_search. Here are build failure links (if RTD permits you to follow them...)

• Attempt 1
  • Just added 'sphinx_search.extension' to conf.py extensions variable
• Attempt 2
  • Included import sphinx_search in conf.py
• Attempt 3
  • Added identical requirements.txt file

Can you suggest what I am doing wrong?

Currently modal is positioned at the center of the page with this css:
https://github.com/rtfd/readthedocs-sphinx-search/blob/358d30f80c8f6c56d21c0d58e63f71fcd6d930c4/sphinx_search/_static/css/rtd_sphinx_search.css#L30-L36

But in some screen sizes (like: 914x669), the text become blurry. Eg -

Blurry Text:

Clear Text:

This can be due to transform property because at some screen sizes it will result in fractions of pixels.
We don't want blurry text, so we have two options -

• adjust current css to remove this glitch.
• position the modal at the center with some other css properties.

Note: Can't use flex-box because it was acting weird with IE 11

This test will fail sometimes

It probably needs to wait some time till the search popup is shown, maybe similar to

It's pretty common to hit enter at the end of the search query and expect the search query to be submitted, but instead the user is redirected to the Sphinx search page. I've noted this UX issue in the past and I've had feedback that this UX is confusing as well.

This is probably more of an issue for the addons implementation, which probably won't repeat this pattern either way. But noting here in case for now.

In #116 Underscore was removed, and the pattern was shifted to native DOM manipulation.

One potential pattern to consider for future releases could be to use an HTML template inline in the output, as a Sphinx template. Effectively:

<html>
  <head>
    <script type="text/html" id="search-template">
      <div class="search__header">
        {{ _("Search results") }}
      <div class="outer__html">
        <div class="header">
          ...
        </div>
        ...
      </div>
    </script>
  </head>
</html>

This gives a template that can be targeted by our search JS, and manipulation of the template would happen with some data binding logic, or a more simple DOM search and replace.

The benefit here is that it is customizable at the Sphinx theme/template level, and can incorporate localization during the Sphinx build. Currently the search window will always be English. Localization is also possible in the JS now, but would have to be an additional step to be hooked into during building.

Over at Godot Docs we have an issue setting up our custom dark theme with this extensions because there are inlined styles, which is making them harder to override. The specific issue is with empty search results, setup here:

I would appreciate if you've changed those three inlined rules to a stylesheet class.

Thanks for this great looking enhancement to docs search. I've followed the install docs. This is very possibly a rookie error, but what am I doing wrong here when rebuilding our docs on ReadTheDocs?

conf.py:

extensions = [
    'sphinx.ext.autosectionlabel',
    'sphinx_search.extension',
]

Build command:

python -m sphinx -T -E -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html

Error:

Running Sphinx v1.8.6
loading translations [en]... done

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/research-handbook-security-force-monitor/envs/latest/lib/python3.11/site-packages/sphinx/registry.py", line 472, in load_extension
    mod = __import__(extname, None, None, ['setup'])
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'sphinx_search'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/research-handbook-security-force-monitor/envs/latest/lib/python3.11/site-packages/sphinx/cmd/build.py", line 300, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/research-handbook-security-force-monitor/envs/latest/lib/python3.11/site-packages/sphinx/application.py", line 228, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/research-handbook-security-force-monitor/envs/latest/lib/python3.11/site-packages/sphinx/application.py", line 449, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/research-handbook-security-force-monitor/envs/latest/lib/python3.11/site-packages/sphinx/registry.py", line 475, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname, err)
sphinx.errors.ExtensionError: Could not import extension sphinx_search.extension (exception: No module named 'sphinx_search')

Extension error:
Could not import extension sphinx_search.extension (exception: No module named 'sphinx_search')

Hi thank you for this awesome project. I encountered some issue that the input box doesn't show query string, it is the same as the background color, below is the screen shot. As you can see, the query string is s3pathlib, but it only show when I select it.

This is my conf.py file, the project is open source, what I did wrong? Or is it a bug? https://github.com/aws-samples/s3pathlib-project/blob/main/docs/source/conf.py

A few issues that I have been hitting consistently:

• When I target the search box to type a search query, I'm always too early typing. The delay introduced by the transition fade in is too slow and this usually results in my vim keybindings closing the window or doing something unwanted. Delay should be removed or reduced to resolve this issue. Ideally, the normal search box should be reused for this purpose, and perhaps a popup only occurs on key press events.
• If you hit enter on the search popup, which I inevitably do, you are brought to the default search page. On this page, the search query is in the search box, but if you select the search box to search again, the search query is not in the popup search box

• Escape key could close the popup

Currently, either the tests for both -- chrome and firefox -- will run or none will run.
We want to select the browser for tests.
Like:

pytest -v --chrome (runs the tests with chrome driver)
pytest -v --firefox (runs the tests with geckodriver)
pytest -v (runs the tests with both drivers)

We are currently suggesting the following configuration:

# https://docs.readthedocs.io/page/reference/environment-variables.html
project = os.environ["READTHEDOCS_PROJECT"]
version = os.environ["READTHEDOCS_VERSION"]

# Include results from subprojects by default.
rtd_sphinx_search_default_filter = f"subprojects:{project}/{version}"

But these variables collide with the Sphinx configuration variables project and version, which aren't always the project/version slug -- they can be a verbose name established by the documentation author.

We should prefix our variables in documentation to make them unique, but it also looks like the default configuration uses project directly, which will have side effects if the project name is not the RTD slug.

https://github.com/readthedocs/readthedocs-sphinx-search/blob/main/docs/configuration.rst?plain=1#L25

It would be neat to be able to search a subset of the docs. An example:

if I did a search at https://docs.readthedocs.io/en/latest/development/install.html -- I had the option to only search inside development inside the docs. This would work similarly well with /guides/ and other "sections".

I think the best option here will be to enable authors to define sections that they want to be able to search within. We have HTMLFile's, so we could see what sections of files users have, and let them create a config that sets these sections as searchable. This could look like:

# .readthedocs.yml

search:
  sections:
    - /development/: Developer docs
    - /guides/: User Guides
 

We could also in theory auto-generate this from the toctree caption argument, or other similar automatic approaches.

@dojutsu-user has an initial demo of this that parses the URL directly from the current page. This is one possible option, but we likely want to let users have a bit more knowledge and UX around sections. Need to think about this more.

We should generate API docs for our JS code. We could try this with autoapi and if that doesn't work, we should try sphinx-js

We don't want to use gulp, it would be better if we can switch everything to webpack.

If I use intersphinx to link other sphinx instances e.g.

intersphinx_mapping = {
    'ewb': ('https://ewb.readthedocs.io/en/latest/', None),
    'rdf': ('https://rdfabout.readthedocs.io/en/latest/', None),
}

how to configure sphinx-search to search those instances for a specified string?

For example, looking here: https://readthedocs-sphinx-search.readthedocs.io/en/latest/customization.html#custom-styles

<a href="/api-v2?highlight=api">
              <h2 class="search__result__title">
                     API v2
                     <br />
              </h2>
 </a>

Search is relative to the page from which the search is launched.

Is it possible to specify other search domains - following the intersphinx method to :ref: another sphinx instance?

docs for frontend are not present
like npm install, gulp

For instance, if my system is dark mode , the search box will change its color to dark, And when the system is in light mode, the search box will change its color to a light one. l know that dark reader can do this , but is there any method to support it originally, l believe not everyone will install dark reader on their laptop. l have noticed that l can achieve this through custom.css , but how can l change the color automatically? Or has any already done that and would you please share your custom.css? Thanks!

Best
Daniel

This would be a more simple structure and use CSS for spacing instead of br elements, and use the html tag a little more "semantically" (don't know if this is a word p: what I mean is for example we are using span tags for titles, and even we have a div inside span tags).

The current structure is

ref #116

Up until now, you install your tests module globally, which is wrong.

Steps to reproduce it

1. go to https://docs.readthedocs.io/en/latest/
2. click on search
3. type configuration
4. hit Enter

Actual result

You are redirected to https://docs.readthedocs.io/en/latest/search.html?q=configuration&check_keywords=yes&area=default which is the default search (instead of the Search As You Type)

Expected result

I was expecting that it will just send the current query to the backend and do nothing, basically.

In case we want to have a fallback to the default search result, I think the usage of Enter has to be communicated in the UI.

Is there a way to configure search to act as if a wildcard (*) is present at the end of the user-entered search string? Based on feedback I've received, this behavior is expected by some and they think the search is broken since it doesn't do that (by default). I didn't see anything about this in the docs, but may have overlooked something.

If the search screen is closed (by clicking "X", hitting escape, etc.) and then re-opened by clicking in the search input or pressing "/", the search term remains in the input field but no results are displayed unless it is edited. It seems that the search function should be triggered if the screen opens with a search term already defined.

Search results returned after search term typed in:

After closing and re-opening the search screen without modify anything:

This extension only works when the content is online, but we also generate downloadable files for offline reading.

Ref: readthedocs/readthedocs-sphinx-ext#63 (comment)

It probably needs to replicate the ONLINE_BUILDERS list from the other extension

Our RTD search has a lot of nice filters on it. We should expose this with a a fancier UI element for filters in the extension, along with having them in the query string.

I'm imagining something similar to this:

Having the checkboxes that at least by default includes subprojects.

Since sphinx 6.0, they have removed support of the jQuery and underscore.js frameworks (https://www.sphinx-doc.org/en/master/changes.html#id37). This makes this library unusable until we adopt the workaround mentioned or downgrade to sphinx 5.

Am testing features here and have some observations...

• Each time I want to adjust a search string, the pop-up window begins with empty text, even though the RTD search text field shows the text I last entered (or there-abouts...it winds up being subtley altered. For example any + is removed).
• Searching for endian +-silo returns 9 pages which tells me its return pages that include either endian or silo and not pages that contain endian but do not contain silo.
• + operator seems wholly ignored. In fact, it gets removed when RTD echos the search string back
• All these search strings return the same result chunk fortran, chunk +fortran chunk + fortran, chunk | fortran
• -silo returns all pages (silo is used on some pages).

So, either I am wholly mis-understanding how this is supposed to work or the search functionality is not working as documented.

Every time you type a character, the history is updated. This makes it hard to go back to the previous page.

https://docs.readthedocs.io/en/stable/?rtd_search=term
https://docs.readthedocs.io/en/stable/?rtd_search=ter
https://docs.readthedocs.io/en/stable/?rtd_search=te
https://docs.readthedocs.io/en/stable/?rtd_search=t
<actual previous page>

As described in readthedocs/readthedocs.org#7896, this extension interferes somehow with the sphinx-tabs extension. I think it may collide with some global function/var.

Steps to reproduce it

1. search for a term (for example a configuration option)
2. click on the result to go to the Configuration page
3. click on the search again
4. search for another term that has a hit in the configuration page (but different anchor)
5. click on that result

Expected result

Move to the section of the hit and hide the search box.

Actual result

Search box is not hidden.

NOTE: I'm using "Configuratio page" as example but the required thing is to be the same page in both results

Update gitignore from https://github.com/github/gitignore

When I click on the search bar and I immediately start typing, 90 % of the times the first characters do not get typed, as demonstrated here:

It happens to me a lot and it's quite annoying.

It's small, but we need the fix from #108 in order to use this extension in our workflow -- if it's possible to do a new release we'd really appreciate it!

We should probably remove the sphinx from the name of this extension, because I believe it should work fine with mkdocs. We might just want to name it readthedocs-search or readthedocs-livesearch or something.

I was looking into how the pydata sphinx theme could support this search functionality, but was a bit confused by the documentation so asking questions here to help clarify.

The custom search input docs

Suggest that you need a structure like this:

<div role="search">
   <form action="search.html" method="get">
      <input type="text" name="q" placeholder="Search docs" />
   </form>
</div>

However, in the pydata theme, we have a little button that will pop up a search window, rather than a search field:

Clicking this button, or typing Ctrl+K will cause the search window to pop up:

It has this structure:

<button class="btn btn-sm navbar-btn search-button search-button__button" title="" aria-label="Search" data-toggle="tooltip" data-original-title="Search">
  <i class="fa-solid fa-magnifying-glass"></i>
</button>

Do we need to find some way to put an input in there for this to work? Or can we somehow get the sphinx RTD search to work with the button some other way?