search

pydata / pydata-sphinx-theme

A clean, three-column Sphinx theme with Bootstrap for the PyData community
https://pydata-sphinx-theme.readthedocs.io
BSD 3-Clause "New" or "Revised" License
623 stars 322 forks source link

Search-as-you-type UX built on top of built-in Sphinx search tools #1977

Open kaycebasques opened 2 months ago

kaycebasques commented 2 months ago

Hello! pigweed.dev switched over to PyData Sphinx Theme (PST) last week. We're happy to join the family :)

I managed to cobble together an inline search AKA search-as-you-type UX built on top of Sphinx's built-in search tools:

search-as-you-type.webm

Would you all be interested in me upstreaming this into PST?

Here's the core logic: https://github.com/google/pigweed/blob/03466a70189630fc2d659f919c6f9eb141effe54/docs/_static/js/pigweed.js#L22-L128

It requires loading the built-in search tools on each page: https://github.com/google/pigweed/blob/03466a70189630fc2d659f919c6f9eb141effe54/docs/layout/layout.html#L29-L32

I can set it up as an opt-in feature (i.e. you have to flip some config flag in conf.py to True before it's enabled on any site).

It did require using the built-in search tools a bit beyond their intended scope. I can kick off a discussion in the upstream Sphinx repo to check that they're cool with supporting this type of usage.

And of course there's lots of room to improve / polish the UI

drammock commented 2 months ago

This would be a big win for our users. I don't want to speak for other maintainers but AFAIC this should be full speed ahead

kaycebasques commented 2 months ago

@drammock LMK who else I should get onboard before proceeding

drammock commented 2 months ago

@drammock LMK who else I should get onboard before proceeding

@trallard @gabalafou and @Carreau (assuming @12rambau is already on board, as he was attempting similar things already a year or so ago, but stalled)

12rambau commented 2 months ago

I'm completely onboard there are multiple attempts on stale in my personnal forks. I wanted to achieve the same level of fluidity as they get in the sphinx immaterial theme. I think it would be be simlply awesome to have an out of the box solution for this. Implementing what you already have would be wonderful and we can iterate on the UX once the JS logic is there.

trallard commented 2 months ago

I am +1 on getting this in PST.

kaycebasques commented 2 months ago

Great! It sounds like there is sufficient quorum. I will start my upstreaming PR this week.

kaycebasques commented 1 month ago

(status update) I have a conference early next week and then should have more time to continue work on this