readthedocs / readthedocs-sphinx-search Goto Github PK
View Code? Open in Web Editor NEWDeprecated: Enable search-as-you-type feature for docs hosted by RTD.
Home Page: https://readthedocs-sphinx-search.readthedocs.io/
License: MIT License
Deprecated: Enable search-as-you-type feature for docs hosted by RTD.
Home Page: https://readthedocs-sphinx-search.readthedocs.io/
License: MIT License
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.
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>
Currently, travis is running tests for only chrome and firefox.
We want IE and MSEdge also.
Move to the section of the hit and hide the search box.
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
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
Update the API to call our new API:
https://docs.readthedocs.io/en/stable/server-side-search/api.html#api-v3
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
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?
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.
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?
Update gitignore from https://github.com/github/gitignore
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:
subprojects:<slug>
prepended to the search in some fashionIt 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.
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.
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 -
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 -
Note: Can't use flex-box because it was acting weird with IE 11
Up until now, you install your tests module globally, which is wrong.
Hi all ๐๐ผ
We've deprecated this extension in favor of the new Read the Docs Addons, that includes a search addon. These addons are going to be enabled by default to all projects building on Read the Docs starting on October 7th, 2024. Read the full announcement at Read the Docs Addons enabled by default blog post.
The new search addon uses the exact same API backend, has a fresh UI1 and more features (eg. filters and recent searches). Besides, it supports any documentation tool, not only Sphinx, allowing you to perform a search across all the projects at once.
If you are looking for a "Search as you type" Sphinx extension, we recommend you to not install this extension and enable Read the Docs Addons in your project instead.
If you are already using this extension, you can keep using it, but keep it mind the repository is going to be archived and it won't receive further features or fixes. However, we recommend you to migrate to Read the Docs Addons before October 7th to avoid any potential incompatibility.
we plan to continue making improvements here. โฉ
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 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.
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.
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
readthedocs-sphinx-search/docs/customization.rst
Lines 31 to 137 in 225353f
ref #116
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.
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')
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.
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.
We don't want to use gulp, it would be better if we can switch everything to webpack.
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...)
'sphinx_search.extension'
to conf.py
extensions
variableimport sphinx_search
in conf.pyrequirements.txt
fileCan you suggest what I am doing wrong?
Am testing features here and have some observations...
+
is removed).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 backchunk 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.
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:
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)
This test will fail sometimes
readthedocs-sphinx-search/tests/test_ui.py
Lines 150 to 155 in 526eb58
It probably needs to wait some time till the search popup is shown, maybe similar to
readthedocs-sphinx-search/tests/test_ui.py
Lines 283 to 288 in 526eb58
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.
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.
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.
docs for frontend are not present
like npm install, gulp
This is likely bc of the shortcut feature, we should make it pass when the search dialog is already open
A few issues that I have been hitting consistently:
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.
Currently, closing the search modal has got no animation.
It would be nice to have some (just like the opening of the modal has)
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.
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
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
configuration
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)
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.