Finding API documentation via the website search

[alexander-held]

Summary

I was trying to find whether return_result_obj is documented on the website. This is a bit tricky to find, as it can be passed to e.g. pyhf.infer.mle.fit but comes in through the mixin for the optimizer, where it is indeed documented: https://pyhf.readthedocs.io/en/v0.7.0/_generated/pyhf.optimize.mixins.OptimizerMixin.html#pyhf.optimize.mixins.OptimizerMixin.minimize.

When I search for return_result_obj in the search bar on the top left of the page, I only see a link to the source code however. Is it possible to also expose the API documentation there?

Documentation Page Link

https://pyhf.readthedocs.io/en/v0.7.0/search.html?q=return_result_obj&check_keywords=yes&area=default

Code of Conduct

• [X] I agree to follow the Code of Conduct

[matthewfeickert]

Is it possible to also expose the API documentation there?

Good question. I don't have much experience with the search functionality with Sphinx sites, but this would indeed be nice to have.

[matthewfeickert]

@alexander-held do you happen to have any examples of projects with docs that have search like this that works as expected? I appreciate this is a bit of a niche question to try to ask you to find.

[alexander-held]

The awkward docs seem to support this, at least to some extent: https://awkward-array.readthedocs.io/en/stable/search.html?q=mask_identity&check_keywords=yes&area=default. It seems like underlines might not be supported though (?) as check_valid only finds valid but should point to e.g. https://awkward-array.readthedocs.io/en/stable/_auto/ak.Array.html.

[alexander-held]

I believe the underline might be the actual issue here, as e.g. maxiter seems to work fine in the pyhf API docs.

[matthewfeickert]

@jpivarski @agoose77 Do you have any insights here into what Awkward is doing to allow this?

[jpivarski]

Whenever I've built a Sphinx site, the search worked out-of-the-box, but it usually wasn't very good at finding exactly what I'm looking for. That is, it didn't have Google-quality fuzziness and ranking of the results. But I also didn't test the search box very often. It may have been broken for some intervals of time and I wouldn't know it. It works now. :)

@agoose77, did you do something special for our new search box? (It's formatted differently, like a MacOS Spotlight Search, but I'm guessing that the engine is the same as before, right?)

[agoose77]

I'm guessing that the engine is the same as before

Right, the formatting is indeed just a theming choice.

Ultimately, what determines the utility of the search box is probably RTD's server-side search integration. It falls back onto the Sphinx search if no results are found, but otherwise uses data scraped from the HTML. It might be possible to write a Sphinx extension that exposes function arguments to the search in a more indexable fashion, but I'm not sure. There is this extension that apparently makes :param: blocks linkable. This would likely show them in the search index, though I won't vouch for it as a solution.

The examples of Awkward are actually indexing the function docstring body, which is different to the signature itself. Additionally, you can perform stricter queries with the appropriate search keywords to e.g. deal with underscores: https://docs.readthedocs.io/en/stable/guides/advanced-search.html#using-advanced-search-features