Update Documentation

[mgrover1]

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:

• Add a "how to build a catalog"
• What is intake-esm doing with my data?
• What is a dictionary of datasets/collection?
• How do I add a derived variable?
• How to disable aggregations in to_dataset_dict()
• How to modify groupby_attrs at runtime (DOC: Add section on intake-esm keys #522 )
• How to save a subsetted catalog (Update how to guides #523 )
• Document the skip_on_error flag in to_dataset_dict()
• How to load a single key via the cat[key].to_dask() (DOC: Add section on intake-esm keys #522 )
• How to use the cat.keys_info() to retrieve information about keys (DOC: Add section on intake-esm keys #522 )
• Guide on how to debug when things go wrong...
• Overview chapter in User Guide fails to build (unique takes no arguments) #404
• Switch over to the furo theme #412: furo theme

Based on this documentation system, we should cover

• Tutorials
• How to Guides
• Explanation
• Reference

[mgrover1]

Related ESDS blogs

Tutorials

• "CESM2-LE Reproduction of Kay et al. 2015"
• "An Example of Using Intake-ESM"

How to

• "Using Intake-ESM’s New Derived Variable Functionality"
• "Building an Intake-esm catalog from CESM2 History Files"

Explanation

• "Creating Visualizations of Intake-ESM Catalogs"
• "Debugging Intake-ESM Process for Reading in CMIP6"

Reference

Gallery?

• "Reimagining Diagnostics Through the Use of the Jupyter Ecosystem"
• "Benchmarking Performance of History vs. Timeseries Files"
• "Regridding High Resolution Observations to a High Resolution Model Grid"
• "Intake-ESM Holoviews Diagnostics"
• "Using Intake-ESM to Analyze Data from CESM2-LE"
• "Creating Model Documentation Using Jupyterbook and Intake-esm"

[mnlevy1981]

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?

[andersy005]

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...

[jukent]

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

[wachsylon]

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

[mgrover1]

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.

[andersy005]

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]

@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:

• Add a "how to build a catalog"
• What is intake-esm doing with my data?
• What is a dictionary of datasets/collection?
• How do I add a derived variable?
• How to disable aggregations in to_dataset_dict()
• How to modify groupby_attrs at runtime
• How to save a subsetted catalog
• Document the skip_on_error flag in to_dataset_dict()
• How to load a single key via the cat[key].to_dask()
• Guide on how to debug when things go wrong...
• Overview chapter in User Guide fails to build (unique takes no arguments) #404
• Switch over to the furo theme #412: furo theme

Based on this documentation system, we should cover

• Tutorials
• How to Guides
• Explanation
• Reference

[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