intake-esm icon indicating copy to clipboard operation
intake-esm copied to clipboard

Published 20 hours ago • verified publisher icon intake

Update Documentation

Open mgrover1 opened this issue 2 years ago • 9 comments

Based on conversations regarding the recent changes, and user feedback, it would be good to do a review of our current documentation, finding areas for improvement. Examples include:

  • [x] Add a "how to build a catalog"
  • [ ] What is intake-esm doing with my data?
  • [ ] What is a dictionary of datasets/collection?
  • [x] How do I add a derived variable?
  • [ ] How to disable aggregations in to_dataset_dict()
  • [x] How to modify groupby_attrs at runtime (#522 )
  • [x] How to save a subsetted catalog (#523 )
  • [ ] Document the skip_on_error flag in to_dataset_dict()
  • [x] How to load a single key via the cat[key].to_dask() (#522 )
  • [x] How to use the cat.keys_info() to retrieve information about keys (#522 )
  • [ ] Guide on how to debug when things go wrong...
  • [x] https://github.com/intake/intake-esm/issues/404
  • [x] https://github.com/intake/intake-esm/pull/412: furo theme

Based on this documentation system, we should cover

  • Tutorials
  • How to Guides
  • Explanation
  • Reference

mgrover1 avatar Nov 24 '21 18:11 mgrover1

Related ESDS blogs

Tutorials

How to

Explanation

Reference

Gallery?

mgrover1 avatar Nov 24 '21 18:11 mgrover1

I'm working on a branch to address the

Add a "how to build a catalog"

tickbox. There's already a a question about it in the FAQ, though the answer is more of a non-answer... so I was going to start by updating that page with step-by-step instructions. Is that sufficient, or should there be a new page elsewhere in the docs as well?

mnlevy1981 avatar Nov 24 '21 19:11 mnlevy1981

I think a notebook in docs/source/user-guide would suffice for the time being. We shall figure out where this belongs when we rearrange the docs...

andersy005 avatar Nov 24 '21 19:11 andersy005

I'm going to start working on "What is intake-esm doing with my data?"

jukent avatar Dec 20 '21 18:12 jukent

Hi everyone, fyi, I also provide some tutorials here for dkrz catalogs. I also cover how to merge two catalogs.

Can I contribute with one of those? Do you know about activities for defining name templates for catalogs and a registry for catalogs?

Best, Fabi

wachsylon avatar Mar 11 '22 12:03 wachsylon

Hi @wachsylon - sorry for the very delayed response. Those look like great tutorials!

Contributions are welcome - the repo we have been using for a registry of catalogs has been this repo https://github.com/NCAR/intake-esm-datastore .

We are taking a look at the PR you submitted there, hopefully getting feedback there + merging soon.

mgrover1 avatar Aug 23 '22 19:08 mgrover1

Just realized @wachsylon's tutorials cover topics that are worth including in intake-esm's proper documentation. Therefore, i'm re-opening this issue

andersy005 avatar Sep 16 '22 01:09 andersy005

@mgrover1, do you plan on covering the remaining tasks in this list? i'd be happy to help... just want make sure there's no duplication of efforts

Based on conversations regarding the recent changes, and user feedback, it would be good to do a review of our current documentation, finding areas for improvement. Examples include:

Based on this documentation system, we should cover

  • Tutorials
  • How to Guides
  • Explanation
  • Reference

andersy005 avatar Sep 16 '22 01:09 andersy005

@wachsylon, could i interest you in contribute a PR with some of the contents from your amazing tutorials? :) No pressure if you don't have time. i can help with this and would certainly credit you

andersy005 avatar Sep 16 '22 01:09 andersy005