Docs: extend or workaround shallow Sphinx search
@sadielbartholomew is already working on this.
Since Mar 24, 2020.
- Dominant language
- Python
- Stars
- 150
- Forks
- 23
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 2
Description
A user has reported they find it difficult to navigate the documentation, in particular that the Sphinx in-site search being unhelpful to pinpoint dedicated sections or ones that would be especially relevant given the keywords entered. I agree & have struggled with the default Sphinx search myself for various projects.
The Sphinx default search is very limited (see the labelled items under their Issue tracker), so we should investigate means such as extensions or plugins to improve it for our docs, else provide a workaround.
As a minimum for users, I would like to make it possible to:
- search the page that is currently being viewed only (in the standard multi-page HTML build) [as requested in particular by said user];
- search for multiple words as a phrase (e.g. "domain ancillary" or any of the CFDM construct names, which is quite important!) rather then just lone words;
- priority listing order for matches on section &, then, sub-section etc. headings.
Ideally, we could enable full regex(-like) pattern-matching capability.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.