Indicator search

[aulemahal]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR is a step towards fixing Create subrealms/categories, atmos.temperature, atmos.precipitation, atmos.wind, atmos.mixed, etc, for temperature, precip, wind and mixed indicators #1433
• Tests for the changes have been added (for bug fixes / features)
  • (If applicable) Documentation has been added / updated (for bug fixes / features)
• CHANGES.rst has been updated (with summary of main changes)
  • Link to issue (:issue:number) and pull request (:pull:number) has been added

What kind of change does this PR introduce?

• This rewrites the "Climate Indicators" page of the doc so that it presents a searchable un-categorized list of indicators.
• I also added the "used variables" to the short description.

Does this PR introduce a breaking change?

No.

Other information:

The changes are usable on RTD's build : https://xclim--1454.org.readthedocs.build/en/1454/indicators.html

The first commit is only a prototype. For now, it shows a list of indicators with title, python name and variables. The list is searchable by "free text", but it only looks in the titles. I'd like to:

• Add keywords to the description
• Add the abstract to the description. Should it be directly inserted ? A foldable box ? A mouseover box ?
• Search by keywords (this will be a bit more heavy on the JS side...
  • by realms
  • by variables
• Add a mouseover short description of the variables

[github-actions]

Warning
This Pull Request is coming from a fork and must be manually tagged approved in order to perform additional testing.

[aulemahal]

Latest commit re-implements the idea using an external js package : minisearch. I have given some basic options, but this will allow for more complex features when needed.

I spend way to much time debugging JS... NBsphinx imports a package (require.js) (I'm not sure what for) that is incompatible with minisearch. The final solution is to import the latter first and the former later, but it took me some googling time. I hope I have documented the process that makes the searchable page possible.

EDIT: With most browsers, the Indicators page will not work anymore if you access it with file://path/to/xclim/docs. You need a HTTP server, even locally.

[SarahG-579462]

Looks good, but I don't know jinja well enough. Does everything in sphinx work properly? require.js is loaded, etc?

[SarahG-579462]

I also notice there are quite a few "indicators" of this type included:

is there a way to remove them?

Overall, the titles don't seem to correspond well with the name of the indicator.

[SarahG-579462]

Finally, clicking on the python name for the indicator doesn't seem to consistently point to the id tag in the api page.

[aulemahal]

Ach, the cf indicators are automatically build from generic indices and so their documentation is really weak. I removed them from this page for the time being.

I also fixed the link. I confused "realm" and "module", which is different for the "virtual modules" (icclim, anuclim).

[SarahG-579462]

Ok, looks good now. One thing that might be worth noting is that the search function for the whole site now has two drawbacks:

• Does not include snippet of the search result
• Does not include non-api version of the indicators (Possibly infeasible with the way this is coded?)

[huard]

Is the YAML ID necessary ? It seems overly technical for an overview page.

[aulemahal]

Everybody does the mistake where when building a yaml they put the python namespace name in the base: field, instead of the ID. Like daily_temperature_range instead of dtr .

Ok, not so many people have shared with me their experience in setting up a yaml module, but still I have a 100% error rate for those who did ;). I see how someone knowing xclim and just wanting to build a quick module would appreciate not having to click on each indicator in order to populate their yaml ?

[huard]

Ok, fair enough. Pushed some code to add a mouseover for variables. Changes the styling cause I used a button tag. Having someone with CSS flair look at the styling would be good at this point.

[Zeitsperre]

I'm noticing that many indicators still seem to be pointing to some undefined locations:

Not sure what can be done about that.

[aulemahal]

@Zeitsperre I think I fixed it ?
The reason is that when a search is done, the html is build from the search results themselves, and not from the original list. And we have to specify which fields form the original records to pass through the search results.

[Zeitsperre]

@aulemahal

The Indicator cards are looking good now, well done!

With most browsers, the Indicators page will not work anymore if you access it with file://path/to/xclim/docs. You need a HTTP server, even locally.

Is this still the case? Is there a workaround that you could implement? I tend to build docs locally to preview them, but I suppose we can simply leverage RTD builds for interaction testing?

[huard]

python -m http.server --directory _build/html 9000

[Zeitsperre]

@huard What is this sorcery? Could you modify the Makefile's docs recipe to launch the documentation preview that way?

[aulemahal]

@Zeitsperre here you go!

[huard]

Do you know how to enforce copying static files to the build directory ? make html doesn't do it all the time.

[aulemahal]

Hum, that's what the html_static_path option is for... Maybe remove _build/html/_static each time you update the static files ?