Use Furo documentation theme

[Zeitsperre]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR fixes Dark mode docs #1693
• 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?

• Replaces the sphinx-rtd-theme for the furo documentation theme
• Adapts the conf.py to make use of specific variables for furo
• pygments themes and CSS overrides have been added to ensure adequate contrast of documentation elements in both "dark" and "light" modes
• Adds alternate logos for the "dark" theme
• Updates the docstrings for xclim/data/__init__.py, xclim/core/locales.py, xclim/core/formatting.py, and others
• Synchronizes tooling dependency versions (ruff, black, yamllint)
• generate_indicator_docstring has been adjusted to ensure that information blocks (e.g. Parameters, Returns) always have newlines between them and that call signature attributes are indented four (4) spaces instead of two (2)
• The pygments-affected code blocks in extendxclim.ipynb have been modified to produce nicer outputs

Does this PR introduce a breaking change?

Yes.

• The theme has been completely replaced with furo, which gives us a dark mode for free as well as better navigation scroll bars when viewing pages in landscape mode.
• Indicator docstrings have been modified to ensure that Parameters items conform strictly to numpy-docstring format (indentations of four spaces for attributes, changed from two spaces).

Other information:

The load order of layouts appears to be slightly different, and I'm having trouble getting the indicators.rst search bar to load properly. Likely a very small change is needed.

[Zeitsperre]

@aulemahal (and @SarahG-579462)

Tagging you here for the JavaScript magic. I think the layout files are handled differently or load later. It seems as though the header content that should be adding minisearch.js to the relevant pages isn't working as intended.

[aulemahal]

@Zeitsperre Fixed the javascript and html injection! Furo simply uses a different base template name and jinja blocks.

[Zeitsperre]

Dark mode is looking sharp!

[aulemahal]

I like this! I think there's a little css fiddling needed still.

[SarahG-579462]

Some issues with the css, and some suggestions.

[SarahG-579462]

I think that if we fix the jupyter notebook issue on auto (or remove auto), and fix the yaml issue for numbers, this is good to go.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[aulemahal]

All my concerns have been addressed. This is nice to look at!

[SarahG-579462]

This latest commit fixes the issue with xarray not working in "auto" mode.

It is not the prettiest solution, since it requires redefining the xarray theme variables in the body tag. (in _static/xarray.css)

I chose to update the xarray css variables (e.g. --xr-font-color0) thru the externalized --jp variables that xarray seems to offer. I'm assuming these are jupyter variables. This fix should therefore be compatible with any jupyter output that uses variables set with a scope within body.

Other options would have been:

• Copying the css that furo uses to set variables when swapping to light or dark mode, and adding a selector so that it updates in the root instead of the body.
• Redefining the xarray colours in the body, instead of the offered --jp variables.
  • This might be a better solution, but it does not offer the nicety that is potentially fixing other jupyter notebook output issues.
• wait for an upstream fix in either xarray or furo.
  • The xarray upstream fix could be done in two ways:
    • Add compatibility for the "auto" theme by using a similar css selector to furo, but targeting the :root pseudo-class instead of the body tag (using the :has pseudo-class)
    • Change the xarray default theming to be set in body instead of, or on top of, :root
  • the furo fix would be to:
    • Make the css variables apply to the :root pseudo-clas, instead of/on top of the body tag (once again with the :has pseudo-class.

[SarahG-579462]

Approved! The logo looking unintuitive is very minor, and more a furo issue anyway.