Support the PyData Sphinx Theme

[agriyakhetarpal]

Hi there, thanks for writing this extension! I see that three themes are supported currently; I was wondering if the PyData Sphinx Theme could be supported too in sphinx-docsearch natively, with as less post-configuration steps as possible.

I have recently used it for our project's documentation and it worked albeit with some extra configuration (https://github.com/pybamm-team/PyBaMM/pull/3159), so I would be happy to write a PR to do this (the best approach right now is to add a custom template like the current documentation suggests and loading it at the extension's initialisation step itself).

[kai687]

Hi @agriyakhetarpal and thanks for filing this request. Yes, we want to add support for this theme, but I need to figure out, how to replace the default search in this theme. Adding DocSearch is easy, but preventing the default search from showing up (e.g., with Cmd+K) isn't as easy as the other themes.

If you have an idea, we would welcome a PR or a comment 🙂.

[agriyakhetarpal]

Thank you @kai687, that is great to hear. I read some of the code and I don't think it is possible to override the (Ctrl+K)/(⌘+K) keyboard shortcuts without customising the theme's source code itself, plus I am not well-versed with JavaScript either. However, there are three points that might help:

1. The search box can itself be disabled in the PyData Sphinx Theme's html_theme_options dictionary: it is enabled in the "navbar_persistent" entry by default. Adding a custom search template in _templates/algolia-search.html with the "navbar_persistent": "algolia-search" configuration value will disable it. This might disable the default search on mobile devices and cause the Algolia searchbox to not display in the drawer, but could be fixed using a bunch of custom CSS rules, since I notice that using desktop mode on a browser on a mobile device averts the problem.
2. Sphinx provides functionality to use a Google custom search engine (CSE) code snippet to override the search template using _templates/searchbox.html as described in the Sphinx FAQ, which injects JavaScript to render query-specific search results from Google.
3. The PyData Sphinx Theme uses an event listener to toggle the search field in search-field.html. The CSS rules for it probably contain a z-index of 1000 to make it display over other elements. Overriding the CSS to make the search field vanish behind other elements (with visibility: hidden;) sounds like a good option. The event listener is defined in this file: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js#L224-L241 If it is possible to override this event listener through the extension so as to not perform any actions on pressing the search keyboard shortcut and let Algolia DocSearch's JavaScript do its job, it would be a nice, workaround-like solution that can be documented with sphinx-docsearch; until the theme brings support for customisation for external search solutions natively (https://github.com/pydata/pydata-sphinx-theme/issues/795).

[kai687]

Thank you @agriyakhetarpal for reporting your insights. This is going to be very helpful.

[glemaitre]

@kai687 We finally move the scikit-learn documentation to the pydata-sphinx-theme (https://scikit-learn.org/stable/). We wanted to opt-in to the Algolia Docsearch engine.

We were wondering if:

• there is a way to have template crawling script to have a proper sectioning in the search bar instead of the default "Documentation" section. Basically, I think that the crawler script would be pretty much the same for all library using this theme;
• there is any new work that has been done on the support of the theme?

[kai687]

@glemaitre you encouraged me to take another look at adding support for the "pydata sphinx theme". You can find a preview here.

I never used the 'pydata-sphinx-theme' before, so I'm not sure if I can get it to look good with the first attempt.

Regarding your other question:

there is a way to have template crawling script to have a proper sectioning in the search bar instead of the default "Documentation" section.

This is determined by the lvl0 property of your records, which by default is 'Documentation'.

For example, for the docs of the awesome theme, I have this crawler configuration:

actions: [
    {
      indexName: "sphinxawesome",
      pathsToMatch: ["https://sphinxawesome.xyz/how-to/**"],
      recordExtractor: ({ $, helpers }) => {
        $(".topic-title").remove();

        return helpers.docsearch({
          recordProps: {
            lvl1: "#content h1",
            content: "#content p, #content li",
            lvl0: {
              selectors: "",
              defaultValue: "How To",
            },
            lvl2: "#content h2",
            lvl3: "#content h3",
            lvl4: "#content h4",
          },
          recordVersion: "v3",
          indexHeadings: true,
        });
      },
    },
    {
      indexName: "sphinxawesome",
      pathsToMatch: ["https://sphinxawesome.xyz/demo/**"],
      recordExtractor: ({ $, helpers }) => {
        $(".topic-title").remove();

        return helpers.docsearch({
          recordProps: {
            lvl1: "#content h1",
            content: "#content p, #content li",
            lvl0: {
              selectors: "",
              defaultValue: "Demo",
            },
            lvl2: "#content h2",
            lvl3: "#content h3",
            lvl4: "#content h4",
          },
          recordVersion: "v3",
          indexHeadings: true,
        });
      },
    },
    {
      indexName: "sphinxawesome",
      pathsToMatch: ["https://sphinxawesome.xyz/about/"],
      recordExtractor: ({ $, helpers }) => {
        $(".topic-title").remove();

        return helpers.docsearch({
          recordProps: {
            lvl1: "#content h1",
            content: "#content p, #content li",
            lvl0: {
              selectors: "",
              defaultValue: "About",
            },
            lvl2: "#content h2",
            lvl3: "#content h3",
            lvl4: "#content h4",
          },
          recordVersion: "v3",
          indexHeadings: true,
        });
      },
    },
  ],

It's not very elegant, but it does the job. I've asked around if there's a better way. You can also ask in the Algolia Discord if you haven't already.

[kai687]

Preliminary support for the Pydata Sphinx theme available in version 0.0.6.

If the style needs tweaking, please open a new issue.

[glemaitre]

Thanks @kai687. I'll have a look now to see if we can do something ;)

[glemaitre]

Big thanks at @kai687. I managed to get to a satisfying crawler configuration thanks to the example and I'm working on the integration of with the website. The required changes are pretty small which is super nice.