Algolia docsearch

[agriyakhetarpal]

Description

This PR adds Algolia DocSearch v3 since our application was accepted recently. Third-party search functionality is not supported with PyData Sphinx Theme yet (pydata/pydata-sphinx-theme#202, pydata/pydata-sphinx-theme#795

Therefore, manual templates are added along with the sphinx-docsearch extension from Algolia to render the search bar. This disables the default search bar.

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist:

• No style issues: $ pre-commit run (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
• All tests pass: $ python run-tests.py --all
• The documentation builds: $ python run-tests.py --doctest

You can run unit and doctests together at once, using $ python run-tests.py --quick.

Further checks:

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (79af68d) 99.71% compared to head (b995df8) 99.71%.

❗ Current head b995df8 differs from pull request most recent head e8b482d. Consider uploading reports for the commit e8b482d to get more accurate results

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #3159   +/-   ##
========================================
  Coverage    99.71%   99.71%           
========================================
  Files          248      248           
  Lines        18763    18763           
========================================
  Hits         18709    18709           
  Misses          54       54           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[agriyakhetarpal]

Some updates: there are definitely ways to make Algolia work with the PyData Sphinx Theme—the sphinx-docsearch extension is just a wrapper and does the same thing as adding the necessary JavaScript files in html_js_files, Algolia's custom CSS in html_css_files, and overrides the search button template at the time the Sphinx builder performs the initialisation. Here are some references of how some other libraries' documentation websites built with PST add the search box – all of them use the same, manual process:

1. sgkit documentation (slightly off-set position, they override the fullscreen overlay. They use Algolia v2 however, the other ones below use v3)
2. Orchest documentation (they simply add their own search field in the navbar with PyData's search icon. We can remove the search icon)
3. DeterminedAI documentation (they have their own colour scheme and have customised their theme extensively, but their location is in the left sidebar and it works)
4. Deepchecks documentation (they seem to align the Algolia overlay pretty well to 'join' the navbar just above it)

There seems to be a require.js error in our case both locally and on readthedocs when I try to follow their build processes (it should work out of the box using the above solution of adding the JavaScript and CSS files) so I probably need to investigate. I am not sure how to debug it so I have filed an issue in the Algolia forum on Discourse to seek help and will follow up on any responses I receive.

[agriyakhetarpal]

This should be ready for review/merge now once tests pass—apparently the error about require.js came from nbsphinx since it is used to load interactive widgets in the notebooks (ipywidgets). It also happens to break a lot of other Sphinx extensions that rely on external JavaScript. This explains #3165 (comment), so we now know why the rendered notebooks won't display sliders in the docs, but I think it is a minor compromise since users can download the notebooks anyway or run them in Colab.

I also added a few CSS customisations so that the elements resemble the PyData Sphinx Theme. The new, blazing-fast search can be tried here: https://pybamm--3159.org.readthedocs.build/en/3159/

[Saransh-cpp]

That's super fast! Thanks for working on this, @agriyakhetarpal!

[agriyakhetarpal]

Before we merge this I just want to make sure that the position is correct on smaller screens and try it on a Windows system which uses Ctrl instead of ⌘ in the search box

[Saransh-cpp]

Sounds good, let us know when this is ready to merge.

[agriyakhetarpal]

Good to go now!