search

Ouranosinc / xclim

Library of derived climate variables, ie climate indicators, based on xarray.
https://xclim.readthedocs.io/en/stable/
Apache License 2.0
333 stars 59 forks source link

Documentation #5

Closed huard closed 6 years ago

huard commented 6 years ago

For each index, I think we'll want a short textual description, a longer explanation including the mathematical formula, an example, and references to papers either defining the indicator or using it.

Zeitsperre commented 6 years ago

Would it make sense to use docstrings to an extent? e.g. https://stackoverflow.com/a/24385103/7322852

While the benefits of following reST conventions are lost on Python2, Python3 IDEs can extract type indications from the text and IIRC, we can configure sphinx to extract this info directly to HTML.

huard commented 6 years ago

That's the idea. My preference goes to the numpy doc style, which supports references and examples. I find the rest convention really ugly.

Zeitsperre commented 6 years ago

According to the Python maintainers, reST is the standard (PEP 287) but thankfully, PyCharm has support for all of the docstring types as mentioned here.

So long as we're consistent, my joy will know no bounds.

huard commented 6 years ago

Oh nice ! Good catch. I've created an example for your consideration and critique. Pull the latest from master, build the docs and check out the TG function in the ICCLIM page.

Zeitsperre commented 6 years ago

@huard Question: Will we be using ReadTheDocs to put our documentation online? I'm wondering if it makes sense for me to sign-up and allow them read-access to this repo.

huard commented 6 years ago

Sure, go ahead.

Zeitsperre commented 6 years ago

Docs are now up! https://xclim.readthedocs.io/en/latest/

huard commented 6 years ago

I suggest we close this issue and open more specific tickets for missing documentation chapters.