NCAS-CMS / NCAS-CMS/cf-python

Docs: extend or workaround shallow Sphinx search

Open
#42 0 comments 0 reactions 1 assignee View on GitHub

@sadielbartholomew is already working on this.

Since Mar 24, 2020.

documentation enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.