Contributing and overall doc comments

[Zeitsperre]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR addresses some issues mentioned in [PyOpenSci] Reviewer #1 Comments #1305
• Tests for the changes have been added (for bug fixes / features)
  • (If applicable) Documentation has been added / updated (for bug fixes / features)
• HISTORY.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?

• The CONTRIBUTING page has been moved to the top level of the repository.
• Information concerning the licensing of xclim is clearly indicated in README.
• sphinx-autodoc-typehints is now used to simplify call signatures generated in documentation.
• The SDBA module API is now found with the rest of the User API documentation.
• HISTORY.rst has been renamed CHANGES.rst, to follow dask-like conventions.
• Hyperlink targets for individual indices and indicators now point to their entries under API or Indices.
• Module-level docstrings have migrated from the library scripts directly into the documentation RestructuredText files.
• The documentation now includes a page explaining the reasons for developing xclim and a section briefly detailing similar and related projects.
• Markdown explanations in some Jupyter Notebooks have been edited for clarity
• Removed Mapping abstract base class types in call signatures (dict variables were always expected).

Does this PR introduce a breaking change?

Yes. The docs have been completely reorganized.

Other information:

[Zeitsperre]

It looks as though sphinx-autodoc-typehints might not work for us (130+ warnings on ReadTheDocs) due to a bug that occurs when statically parsing the type information for custom classes in call signatures: tox-dev/sphinx-autodoc-typehints#186

Will check for a workaround or a way of squelching the warnings.

[Zeitsperre]

If I can get this working, the gains are considerable.

Present version of docs:

With sphinx-autodoc-typehints:

[Zeitsperre]

Update

@Ouranosinc/xclim-core

I've staged a page for us to explain how xclim is different from other projects (see final comment in #1305) with some ipsum dolor text and links to relevant projects. I can get this started, but would appreciate a hand.

It also made sense to concentrate most of the usage targets under the API page, except for the climate indices. The reason is that the API page is already enormous. This also makes it easier to navigate the climate indices, as they now live on their own page.

All these changes were causing hyperlink issues, so to resolve them I decided on the following:

• The modules section of the docs contains hyperlink targets for all functions except for indicators and indices
• The hyperlink targets for indicators and indices will point to entries in User API or under the Indices pages.

This makes it so that we can finally have valid targets that we can share with users that no longer shows the _hidden path, e.g.:

Instead of:

• https://xclim.readthedocs.io/en/stable/xclim.indicators.atmos.html#xclim.indicators.atmos._temperature.biologically_effective_degree_days

We now have:

• (proposed) https://xclim.readthedocs.io/en/stable/api.html#xclim.indicators.atmos.biologically_effective_degree_days

IMO, this is a major improvement, but it's a bit of a departure, so I'd like to hear peoples' thoughts on this.

Thanks!

[bzah]

My 2 cents:
I really like having all the indices listed in the menu.
I also like that the API is a single page even though it's a bit "slow" to load.

A few suggestions (not specific to the PR but to xclim's doc) :

• I find "ALL MODULES" > xclim and "USER API" > API sections redundant.
• In the long run it could be interesting to divide the documentations into categories to group doc pages that belongs together. It could be categories such as the ones proposed in diataxis. It's really tedious to do on existing doc though.
• I find it unusual to use the word "History" for the Change logs. I would prefer "Changelog" (like dask) or "Release Notes" like (like pandas or numpy).
• I would suggest putting a sentence + link to Indicator on the Indices page, to encourage user to use the Indicator class instead. As per my understanding, you really want indices to be a technical topic in xclim and Indicators to be the user frontend right ?

Overall: great changes thanks!
Link to PR's readthedoc build I used for review: https://xclim--1308.org.readthedocs.build/en/1308/readme.html .

[Zeitsperre]

(Woops, hit the wrong button!)

My 2 cents: I really like having all the indices listed in the menu. I also like that the API is a single page even though it's a bit "slow" to load.

Agreed. I think having the Indicators specifically under API gives users the impression that this is how you use the library.

• I find "ALL MODULES" > xclim and "USER API" > API sections redundant.
• In the long run it could be interesting to divide the documentations into categories to group doc pages that belongs together. It could be categories such as the ones proposed in diataxis. It's really tedious to do on existing doc though.

I think the idea of separating these two come from that design approach. Other scientific libraries use this layout philosophy (like numpy and dask. We're halfway there, IMO. (I've made this into an issue to be discussed at out next monthly planning).

• I find it unusual to use the word "History" for the Change logs. I would prefer "Changelog" (like dask) or "Release Notes" like (like pandas or numpy).

Agreed. Changed.

• I would suggest putting a sentence + link to Indicator on the Indices page, to encourage user to use the Indicator class instead. As per my understanding, you really want indices to be a technical topic in xclim and Indicators to be the user frontend right ?

Done.

Overall: great changes thanks! Link to PR's readthedoc build I used for review: https://xclim--1308.org.readthedocs.build/en/1308/readme.html .

Thanks!

[coveralls]

Coverage: 91.769% (+0.002%) from 91.767% when pulling 9bba321 on reviewer_1_comments into a9efcbe on master.

[Zeitsperre]

I've staged the Purpose page to explain what xclim is and how it differs from other projects. Once we have a more finalized paper, we can pull information directly from that.

I'll be adding one or two comments in the section this afternoon, but aside from that, I think this PR is in good shape and will address several points raised by the reviewer. If there are no other comments, I'll be merging this by the end of the day.