Putting fre catalog docstrings into plain sentences - #905
Conversation
Clarify `fre catalog` docstrings while preserving `validate` wording
| @click.group(help=click.style(" - catalog subcommands", fg=(64,94,213))) | ||
| def catalog_cli(): | ||
| ''' entry point for click into fre catalog cli calls ''' | ||
| """This command group exposes the ``fre catalog`` subcommands.""" |
| ''' | ||
| entry point for fre catalog subcommands | ||
| ''' | ||
| """This module defines the ``fre catalog`` CLI commands.""" |
There was a problem hiding this comment.
Will the definition of a catalog and more detailed descriptions of the click options be coming soon? 😁
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #905 +/- ##
=======================================
Coverage 82.09% 82.09%
=======================================
Files 67 67
Lines 3736 3736
=======================================
Hits 3067 3067
Misses 669 669
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
| ''' | ||
| entry point for fre catalog subcommands | ||
| ''' | ||
| """ This module defines the ``fre catalog`` CLI commands. |
There was a problem hiding this comment.
Frecatalog defines the fre catalog Click subcommands to catalog a dataset of climate output data into CSV and JSON files.
| It builds catalog CSV and JSON files that form a structured index of datasets and | ||
| their metadata, allowing analysis tools to discover, query, and load data consistently. | ||
|
|
||
| These data catalogs enable data discoverability regardless of the underlying data format |
There was a problem hiding this comment.
Discoverability is a nice word but I think it's encapsulated in the previous sentence. Not sure if this sentences is needed.
| These data catalogs enable data discoverability regardless of the underlying data format | ||
| (e.g., NetCDF, Zarr). The cataloging ecosystem is composed of three main components: | ||
|
|
||
| 1. Catalog Specification (JSON): A single file that provides overarching metadata about |
There was a problem hiding this comment.
A single file that provides overarching --> a global file that contains overarching
There was a problem hiding this comment.
It's probably because I have zero knowledge about fre catalog, but not sure what overarching metadata is.. and what extensible metadata is..
There was a problem hiding this comment.
This is the exact language used for the official tool documentation. I'll probably keep this part as it.
| 1. Catalog Specification (JSON): A single file that provides overarching metadata about | ||
| the catalog. It supports extensible metadata and identifies how multiple distinct | ||
| files can be aggregated into a single cohesive "dataset." | ||
| 2. Catalog (CSV): A file that acts as the index for the data collection, providing |
There was a problem hiding this comment.
A file that acts as the index --> Index file for the data collection. Includes paths to the data files
Is this clause "and their associated metadata at a user-defined granularity" needed?
There was a problem hiding this comment.
I'll take the suggestion. As for your question, I'd say yes.
| files can be aggregated into a single cohesive "dataset." | ||
| 2. Catalog (CSV): A file that acts as the index for the data collection, providing | ||
| the paths to the data files and their associated metadata at a user-defined granularity. | ||
| 3. Intake-ESM API: Provides a Pythonic interface to query the catalog's contents and |
There was a problem hiding this comment.
Provides APIs to query the catalog and automatically load..
| their metadata, allowing analysis tools to discover, query, and load data consistently. | ||
|
|
||
| These data catalogs enable data discoverability regardless of the underlying data format | ||
| (e.g., NetCDF, Zarr). The cataloging ecosystem is composed of three main components: |
There was a problem hiding this comment.
The cataloging ecosystem relies on Intake-ESM APIs to query the JSON and CSV catalog files:
| @click.option('--append', is_flag = True, default = False) | ||
| @click.option('--verbose', is_flag = True, default = False, help = "Enables verbose mode (Prints additional diagnostic information during catalog generation)") | ||
| @click.option('--overwrite', is_flag = True, default = False, help = "Overwrite existing catalog output files if they already exist") | ||
| @click.option('--append', is_flag = True, default = False, help = "Append to existing catalog output files") |
| append = False, slow = False, strict = False): | ||
| # pylint: disable=unused-argument | ||
| """ - Generate .csv and .json files for catalog """ | ||
| """Build catalog CSV and JSON files from the provided input data.""" |
There was a problem hiding this comment.
from the files in input_path?
| def validate(context, json_path, json_template_path, vocab, proper_generation, test_failure): | ||
| # pylint: disable=unused-argument | ||
| """ - Validate catalogs against controlled vocabulary as provided by particular JSON schemas | ||
| """Validate catalogs against controlled vocabulary as provided by particular JSON schemas |
There was a problem hiding this comment.
Validate JSON catalog in json_path against controlled vocabulary in the JSON schemas in json_template_path
| @click.pass_context | ||
| def merge(context, input, output): | ||
| """ - Merge two or more more catalogs into one """ | ||
| """Merge two or more catalogs into one catalog file.""" |
Describe your changes
Issue ticket number and link (if applicable)
Fixes #XXX (replace XXX with the issue number and GitHub will autolink the PR to the issue)
Checklist before requesting a review
Note: If you are a code maintainer updating the tag or releasing a new fre-cli version, please use the
release_procedure.mdtemplate. To quickly use this template, open a new pull request, choose your branch, and add?template=release_procedure.mdto the end of the url.