From b2dbb145c7d8e1458392bb6c167ea021a62cbb18 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Wed, 27 Mar 2024 09:45:58 -0400 Subject: [PATCH] add quest to pyreverse uml generation + separate in API docs (#498) * generate umls for quest module * make separate API docs pages for icepyx and quest * add manual trigger for uml creation to allow updates after post-approval changes * simplify highest level API TOC to show only class levels * add previous/next navigation buttons to API docs Co-authored-by: GitHub Action --- .github/workflows/uml_action.yml | 4 +- README.rst | 2 +- doc/source/community/resources.rst | 2 +- .../community/resources/IS2_software.rst | 2 + doc/source/conf.py | 4 +- doc/source/index.rst | 1 + doc/source/user_guide/changelog/v0.8.0.rst | 2 +- doc/source/user_guide/changelog/v0.8.1.rst | 2 +- doc/source/user_guide/changelog/v1.0.0.rst | 2 +- .../documentation/classes_dev_uml.svg | 643 ++++++++++-------- .../documentation/classes_quest_user_uml.svg | 64 ++ .../user_guide/documentation/icepyx-quest.rst | 22 + .../user_guide/documentation/icepyx.rst | 16 +- .../documentation/packages_quest_user_uml.svg | 61 ++ doc/source/user_guide/documentation/quest.rst | 13 +- 15 files changed, 532 insertions(+), 308 deletions(-) create mode 100644 doc/source/user_guide/documentation/classes_quest_user_uml.svg create mode 100644 doc/source/user_guide/documentation/icepyx-quest.rst create mode 100644 doc/source/user_guide/documentation/packages_quest_user_uml.svg diff --git a/.github/workflows/uml_action.yml b/.github/workflows/uml_action.yml index ede29cdf8..b85885023 100644 --- a/.github/workflows/uml_action.yml +++ b/.github/workflows/uml_action.yml @@ -3,6 +3,7 @@ on: pull_request_review: types: [submitted] branches: development + workflow_dispatch: jobs: diagrams: @@ -23,7 +24,8 @@ jobs: - name: run pyreverse run: | pyreverse ./icepyx/core -p user_uml -o svg - pyreverse ./icepyx/core -f ALL -p dev_uml -o svg + pyreverse ./icepyx/quest -p quest_user_uml -o svg + pyreverse ./icepyx/core ./icepyx/quest -f ALL -p dev_uml -o svg rm ./packages_dev_uml.svg mv ./*.svg ./doc/source/user_guide/documentation/ - name: Commit changes diff --git a/README.rst b/README.rst index 60220c135..e402fc604 100644 --- a/README.rst +++ b/README.rst @@ -95,7 +95,7 @@ Listed below are example Jupyter notebooks for working with ICESat-2 (IS2). `IS2_data_read-in `_ -`IS2_cloud_data_access (BETA ONLY) `_ +`IS2_cloud_data_access `_ Citing icepyx diff --git a/doc/source/community/resources.rst b/doc/source/community/resources.rst index be3aebaa0..8d60fdee7 100644 --- a/doc/source/community/resources.rst +++ b/doc/source/community/resources.rst @@ -14,7 +14,7 @@ We reserve the right to reject suggested resources that fall outside the scope o Other Ways to Access ICESat-2 Data ---------------------------------- icepyx aims to provide intuitive, object-based methods for finding, obtaining, visualizing, and analyzing ICESat-2 data as part of an open, -reproducible workflow that leverages existing tools wherever possible (see :ref:`Complementary GitHub Repos`) +reproducible workflow that leverages existing tools wherever possible (see :ref:`Complementary GitHub Repositories `) and can be run locally, using high performance computing, or in the cloud using Pangeo. A few other options available for querying, visualizing, and downloading ICESat-2 data files are: diff --git a/doc/source/community/resources/IS2_software.rst b/doc/source/community/resources/IS2_software.rst index 5e3c2ce9a..fc0edaf56 100644 --- a/doc/source/community/resources/IS2_software.rst +++ b/doc/source/community/resources/IS2_software.rst @@ -26,6 +26,8 @@ Most of these packages are callable through Python, though others may require ac - Users may also convert processed data to .las, .csv, and .kml file formats. +.. _complementary_GH_repos_label: + Complementary GitHub Repositories --------------------------------- Here we describe a selection of publicly available Python code posted on GitHub with applicability for working with ICESat-2 data. diff --git a/doc/source/conf.py b/doc/source/conf.py index a77670850..868af3fbc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -77,7 +77,7 @@ autosectionlabel_prefix_document = True autosummary_generate = True numpydoc_show_class_members = False -jupyter_execute_notebooks = "off" +nb_execution_mode = "off" suppress_warnings = ["myst.header"] # suppress non-consecutive header warning # -- Options for HTML output ------------------------------------------------- @@ -90,7 +90,7 @@ html_theme_options = { "logo_only": True, "display_version": False, - "prev_next_buttons_location": None, + "prev_next_buttons_location": "bottom", "navigation_depth": 4, "collapse_navigation": True, } diff --git a/doc/source/index.rst b/doc/source/index.rst index 45047b310..0f8d1e21c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -136,6 +136,7 @@ ICESat-2 datasets to enable scientific discovery. :caption: User Guide user_guide/documentation/icepyx + user_guide/documentation/icepyx-quest user_guide/changelog/index .. toctree:: diff --git a/doc/source/user_guide/changelog/v0.8.0.rst b/doc/source/user_guide/changelog/v0.8.0.rst index 7227a580f..4665ee6a7 100644 --- a/doc/source/user_guide/changelog/v0.8.0.rst +++ b/doc/source/user_guide/changelog/v0.8.0.rst @@ -1,5 +1,5 @@ What's new in 0.8.0 (12 September 2023) ------------------------------------ +--------------------------------------- These are the changes in icepyx 0.8.0 See :ref:`release` for a full changelog including other versions of icepyx. diff --git a/doc/source/user_guide/changelog/v0.8.1.rst b/doc/source/user_guide/changelog/v0.8.1.rst index 5b86c5dec..fe95d8428 100644 --- a/doc/source/user_guide/changelog/v0.8.1.rst +++ b/doc/source/user_guide/changelog/v0.8.1.rst @@ -1,5 +1,5 @@ What's new in 0.8.1 (14 November 2023) -------------------------------------- +-------------------------------------- These are the changes in icepyx 0.8.1 See :ref:`release` for a full changelog including other versions of icepyx. diff --git a/doc/source/user_guide/changelog/v1.0.0.rst b/doc/source/user_guide/changelog/v1.0.0.rst index 904cf82a2..fe0c34a71 100644 --- a/doc/source/user_guide/changelog/v1.0.0.rst +++ b/doc/source/user_guide/changelog/v1.0.0.rst @@ -1,5 +1,5 @@ What's new in 1.0.0 (5 January 2024) ------------------------------------ +------------------------------------ These are the changes in icepyx 1.0.0 See :ref:`release` for a full changelog including other versions of icepyx. diff --git a/doc/source/user_guide/documentation/classes_dev_uml.svg b/doc/source/user_guide/documentation/classes_dev_uml.svg index 84fb2a450..8079985cc 100644 --- a/doc/source/user_guide/documentation/classes_dev_uml.svg +++ b/doc/source/user_guide/documentation/classes_dev_uml.svg @@ -4,389 +4,468 @@ - - + + classes_dev_uml - - + + +icepyx.quest.dataset_scripts.argo.Argo + +Argo + +_apikey : str +_params : list +_presRange : NoneType +_spatial +_temporal +argodata : DataFrame, NoneType +params +presRange +prof_ids : list + +__init__(aoi, toi, params, presRange) +__str__() +_download_profile(profile_number, printURL): dict +_fmt_coordinates(): str +_parse_into_df(profile_data): pd.DataFrame +_valid_params(): list +_validate_parameters(params): list +download(params, presRange, keep_existing): pd.DataFrame +save(filepath) +search_data(params, presRange, printURL): str + + + +icepyx.quest.dataset_scripts.dataset.DataSet + +DataSet + + +__init__ +(spatial_extent, date_range, start_time, end_time) +_fmt_coordinates +() +_fmt_timerange +() +_validate_inputs +() +download +() +save +(filepath) +search_data +() +visualize +() + + + +icepyx.quest.dataset_scripts.argo.Argo->icepyx.quest.dataset_scripts.dataset.DataSet + + + + + icepyx.core.auth.AuthenticationError - -AuthenticationError - - - + +AuthenticationError + + + - + icepyx.core.exceptions.DeprecationError - -DeprecationError - - - + +DeprecationError + + + - + icepyx.core.auth.EarthdataAuthMixin - -EarthdataAuthMixin - -_auth : NoneType -_s3_initial_ts : NoneType, datetime -_s3login_credentials : NoneType -_session : NoneType -auth -s3login_credentials -session - -__init__(auth) -__str__() -earthdata_login(uid, email, s3token): None + +EarthdataAuthMixin + +_auth : NoneType +_s3_initial_ts : NoneType, datetime +_s3login_credentials : NoneType +_session : NoneType +auth +s3login_credentials +session + +__init__(auth) +__str__() +earthdata_login(uid, email, s3token): None - + icepyx.core.query.GenQuery - -GenQuery - -_spatial -_temporal -dates -end_time -spatial -spatial_extent -start_time -temporal - -__init__(spatial_extent, date_range, start_time, end_time) -__str__() + +GenQuery + +_spatial +_temporal +dates +end_time +spatial +spatial_extent +start_time +temporal + +__init__(spatial_extent, date_range, start_time, end_time) +__str__() - + icepyx.core.granules.Granules - -Granules - -avail : list -orderIDs : list - -__init__ -() -download(verbose, path, session, restart) -get_avail(CMRparams, reqparams, cloud) -place_order(CMRparams, reqparams, subsetparams, verbose, subset, session, geom_filepath) + +Granules + +avail : list +orderIDs : list + +__init__ +() +download(verbose, path, session, restart) +get_avail(CMRparams, reqparams, cloud) +place_order(CMRparams, reqparams, subsetparams, verbose, subset, session, geom_filepath) - + icepyx.core.query.Query - -Query - -CMRparams -_CMRparams -_about_product -_cust_options : dict -_cycles : list -_granules -_order_vars -_prod : NoneType, str -_readable_granule_name : list -_reqparams -_subsetparams : NoneType -_tracks : list -_version -cycles -dataset -granules -order_vars -product -product_version -reqparams -tracks - -__init__(product, spatial_extent, date_range, start_time, end_time, version, cycles, tracks, auth) -__str__() -avail_granules(ids, cycles, tracks, cloud) -download_granules(path, verbose, subset, restart) -latest_version() -order_granules(verbose, subset, email) -product_all_info() -product_summary_info() -show_custom_options(dictview) -subsetparams() -visualize_elevation() -visualize_spatial_extent() + +Query + +CMRparams +_CMRparams +_about_product +_cust_options : dict +_cycles : list +_granules +_order_vars +_prod : NoneType, str +_readable_granule_name : list +_reqparams +_subsetparams : NoneType +_tracks : list +_version +cycles +dataset +granules +order_vars +product +product_version +reqparams +tracks + +__init__(product, spatial_extent, date_range, start_time, end_time, version, cycles, tracks, auth) +__str__() +avail_granules(ids, cycles, tracks, cloud) +download_granules(path, verbose, subset, restart) +latest_version() +order_granules(verbose, subset, email) +product_all_info() +product_summary_info() +show_custom_options(dictview) +subsetparams() +visualize_elevation() +visualize_spatial_extent() - + icepyx.core.granules.Granules->icepyx.core.query.Query - - -_granules + + +_granules - + icepyx.core.granules.Granules->icepyx.core.query.Query - - -_granules + + +_granules - + icepyx.core.icesat2data.Icesat2Data - -Icesat2Data - - -__init__() + +Icesat2Data + + +__init__() - + icepyx.core.exceptions.NsidcQueryError - -NsidcQueryError - -errmsg -msgtxt : str - -__init__(errmsg, msgtxt) -__str__() + +NsidcQueryError + +errmsg +msgtxt : str + +__init__(errmsg, msgtxt) +__str__() - + icepyx.core.exceptions.QueryError - -QueryError - - - + +QueryError + + + icepyx.core.exceptions.NsidcQueryError->icepyx.core.exceptions.QueryError - - + + - + icepyx.core.APIformatting.Parameters - -Parameters - -_fmted_keys : NoneType, dict -_poss_keys : dict -_reqtype : NoneType, str -fmted_keys -partype -poss_keys - -__init__(partype, values, reqtype) -_check_valid_keys() -_get_possible_keys() -build_params() -check_req_values() -check_values() + +Parameters + +_fmted_keys : NoneType, dict +_poss_keys : dict +_reqtype : NoneType, str +fmted_keys +partype +poss_keys + +__init__(partype, values, reqtype) +_check_valid_keys() +_get_possible_keys() +build_params() +check_req_values() +check_values() - + icepyx.core.APIformatting.Parameters->icepyx.core.query.Query - - -_CMRparams + + +_CMRparams - + icepyx.core.APIformatting.Parameters->icepyx.core.query.Query - - -_reqparams + + +_reqparams - + icepyx.core.APIformatting.Parameters->icepyx.core.query.Query - - -_subsetparams + + +_subsetparams - + icepyx.core.APIformatting.Parameters->icepyx.core.query.Query - - -_subsetparams + + +_subsetparams icepyx.core.query.Query->icepyx.core.auth.EarthdataAuthMixin - - + + icepyx.core.query.Query->icepyx.core.query.GenQuery - - + + + + + +icepyx.quest.quest.Quest + +Quest + +datasets : dict + +__init__(spatial_extent, date_range, start_time, end_time, proj) +__str__() +add_argo(params, presRange): None +add_icesat2(product, start_time, end_time, version, cycles, tracks, files): None +download_all(path) +save_all(path) +search_all() + + + +icepyx.quest.quest.Quest->icepyx.core.query.GenQuery + + - + icepyx.core.read.Read - -Read - -_filelist -_out_obj : Dataset -_product -_read_vars -filelist -is_s3 -product -vars - -__init__(data_source, glob_kwargs, out_obj_type, product, filename_pattern, catalog) -_add_vars_to_ds(is2ds, ds, grp_path, wanted_groups_tiered, wanted_dict) -_build_dataset_template(file) -_build_single_file_dataset(file, groups_list) -_combine_nested_vars(is2ds, ds, grp_path, wanted_dict) -_read_single_grp(file, grp_path) -load() + +Read + +_filelist +_out_obj : Dataset +_product +_read_vars +filelist +is_s3 +product +vars + +__init__(data_source, glob_kwargs, out_obj_type, product, filename_pattern, catalog) +_add_vars_to_ds(is2ds, ds, grp_path, wanted_groups_tiered, wanted_dict) +_build_dataset_template(file) +_build_single_file_dataset(file, groups_list) +_combine_nested_vars(is2ds, ds, grp_path, wanted_dict) +_read_single_grp(file, grp_path) +load() icepyx.core.read.Read->icepyx.core.auth.EarthdataAuthMixin - - + + - + icepyx.core.spatial.Spatial - -Spatial - -_ext_type : str -_gdf_spat : GeoDataFrame -_geom_file : NoneType -_spatial_ext -_xdateln -extent -extent_as_gdf -extent_file -extent_type - -__init__(spatial_extent) -__str__() -fmt_for_CMR() -fmt_for_EGI() + +Spatial + +_ext_type : str +_gdf_spat : GeoDataFrame +_geom_file : NoneType +_spatial_ext +_xdateln +extent +extent_as_gdf +extent_file +extent_type + +__init__(spatial_extent) +__str__() +fmt_for_CMR() +fmt_for_EGI() - + icepyx.core.spatial.Spatial->icepyx.core.query.GenQuery - - -_spatial + + +_spatial - + icepyx.core.spatial.Spatial->icepyx.core.query.GenQuery - - -_spatial + + +_spatial - + icepyx.core.temporal.Temporal - -Temporal - -_end : datetime -_start : datetime -end -start - -__init__(date_range, start_time, end_time) -__str__() + +Temporal + +_end : datetime +_start : datetime +end +start + +__init__(date_range, start_time, end_time) +__str__() - + icepyx.core.temporal.Temporal->icepyx.core.query.GenQuery - - -_temporal + + +_temporal - + icepyx.core.variables.Variables - -Variables - -_avail : NoneType, list -_path : NoneType -_product : NoneType, str -_version -path -product -version -wanted : NoneType, dict - -__init__(vartype, path, product, version, avail, wanted, auth) -_check_valid_lists(vgrp, allpaths, var_list, beam_list, keyword_list) -_get_combined_list(beam_list, keyword_list) -_get_sum_varlist(var_list, all_vars, defaults) -_iter_paths(sum_varlist, req_vars, vgrp, beam_list, keyword_list) -_iter_vars(sum_varlist, req_vars, vgrp) -append(defaults, var_list, beam_list, keyword_list) -avail(options, internal) -parse_var_list(varlist, tiered, tiered_vars) -remove(all, var_list, beam_list, keyword_list) + +Variables + +_avail : NoneType, list +_path : NoneType +_product : NoneType, str +_version +path +product +version +wanted : NoneType, dict + +__init__(vartype, path, product, version, avail, wanted, auth) +_check_valid_lists(vgrp, allpaths, var_list, beam_list, keyword_list) +_get_combined_list(beam_list, keyword_list) +_get_sum_varlist(var_list, all_vars, defaults) +_iter_paths(sum_varlist, req_vars, vgrp, beam_list, keyword_list) +_iter_vars(sum_varlist, req_vars, vgrp) +append(defaults, var_list, beam_list, keyword_list) +avail(options, internal) +parse_var_list(varlist, tiered, tiered_vars) +remove(all, var_list, beam_list, keyword_list) icepyx.core.variables.Variables->icepyx.core.auth.EarthdataAuthMixin - - + + - + icepyx.core.variables.Variables->icepyx.core.query.Query - - -_order_vars + + +_order_vars - + icepyx.core.variables.Variables->icepyx.core.query.Query - - -_order_vars + + +_order_vars - + icepyx.core.variables.Variables->icepyx.core.read.Read - - -_read_vars + + +_read_vars - + icepyx.core.visualization.Visualize - -Visualize - -bbox : list -cycles : NoneType -date_range : NoneType -product : NoneType, str -tracks : NoneType - -__init__(query_obj, product, spatial_extent, date_range, cycles, tracks) -generate_OA_parameters(): list -grid_bbox(binsize): list -make_request(base_url, payload) -parallel_request_OA(): da.array -query_icesat2_filelist(): tuple -request_OA_data(paras): da.array -viz_elevation(): (hv.DynamicMap, hv.Layout) + +Visualize + +bbox : list +cycles : NoneType +date_range : NoneType +product : NoneType, str +tracks : NoneType + +__init__(query_obj, product, spatial_extent, date_range, cycles, tracks) +generate_OA_parameters(): list +grid_bbox(binsize): list +make_request(base_url, payload) +parallel_request_OA(): da.array +query_icesat2_filelist(): tuple +request_OA_data(paras): da.array +viz_elevation(): (hv.DynamicMap, hv.Layout) diff --git a/doc/source/user_guide/documentation/classes_quest_user_uml.svg b/doc/source/user_guide/documentation/classes_quest_user_uml.svg new file mode 100644 index 000000000..b5ce50192 --- /dev/null +++ b/doc/source/user_guide/documentation/classes_quest_user_uml.svg @@ -0,0 +1,64 @@ + + + + + + +classes_quest_user_uml + + + +icepyx.quest.dataset_scripts.argo.Argo + +Argo + +argodata : DataFrame, NoneType +params +presRange +prof_ids : list + +download(params, presRange, keep_existing): pd.DataFrame +save(filepath) +search_data(params, presRange, printURL): str + + + +icepyx.quest.dataset_scripts.dataset.DataSet + +DataSet + + +download +() +save +(filepath) +search_data +() +visualize +() + + + +icepyx.quest.dataset_scripts.argo.Argo->icepyx.quest.dataset_scripts.dataset.DataSet + + + + + +icepyx.quest.quest.Quest + +Quest + +datasets : dict + +add_argo(params, presRange): None +add_icesat2(product, start_time, end_time, version, cycles, tracks, files): None +download_all(path) +save_all(path) +search_all() + + + diff --git a/doc/source/user_guide/documentation/icepyx-quest.rst b/doc/source/user_guide/documentation/icepyx-quest.rst new file mode 100644 index 000000000..9fc95a40f --- /dev/null +++ b/doc/source/user_guide/documentation/icepyx-quest.rst @@ -0,0 +1,22 @@ +.. _api_doc_ref_q: + +icepyx-QUEST Documentation (API) +================================ + +QUEST and icepyx share the top-level GenQuery class. +The documentation for GenQuery are within :class:`icepyx.Query`. + +.. image:: classes_quest_user_uml.svg + :width: 600 + :alt: UML Class Diagram illustrating the public-facing classes within quest, their attributes and methods, their relationships (e.g. component classes). + +Class diagram illustrating the QUEST component's of icepyx's +public-facing classes, their attributes and methods, and their relationships. +Additional UML diagrams, including a more detailed, developer UML class diagram showing hidden parameters, +are available on `GitHub in the icepyx/doc/source/user_guide/documentation/ directory `_. +Diagrams are updated automatically after a pull request (PR) is approved and before it is merged to the development branch. + +.. toctree:: + :maxdepth: 1 + + quest diff --git a/doc/source/user_guide/documentation/icepyx.rst b/doc/source/user_guide/documentation/icepyx.rst index a8a9a6f8e..eec823e10 100644 --- a/doc/source/user_guide/documentation/icepyx.rst +++ b/doc/source/user_guide/documentation/icepyx.rst @@ -1,27 +1,21 @@ .. _api_doc_ref: -icepyx Documentation (API Reference) -==================================== - -.. image:: packages_user_uml.svg - :width: 600 - :alt: UML package Diagram illustrating the public-facing, high-level packages within icepyx and their relationships. - -icepyx package diagram illustrating the library's public-facing, high-level package structure and their relationships. - +icepyx Documentation (API) +========================== .. image:: classes_user_uml.svg :width: 600 :alt: UML Class Diagram illustrating the public-facing classes within icepyx, their attributes and methods, their relationships (e.g. component classes). icepyx class diagram illustrating the library's public-facing classes, their attributes and methods, and their relationships. -A more detailed, developer UML class diagram showing hidden parameters is available on GitHub in the ``icepyx/doc/source/user_guide/documentation/`` directory. +Additional UML diagrams, including a more detailed, developer UML class diagram showing hidden parameters, +are available on `GitHub in the icepyx/doc/source/user_guide/documentation/ directory `_. Diagrams are updated automatically after a pull request (PR) is approved and before it is merged to the development branch. .. toctree:: + :maxdepth: 1 query read - quest variables components diff --git a/doc/source/user_guide/documentation/packages_quest_user_uml.svg b/doc/source/user_guide/documentation/packages_quest_user_uml.svg new file mode 100644 index 000000000..7ef3ca7d9 --- /dev/null +++ b/doc/source/user_guide/documentation/packages_quest_user_uml.svg @@ -0,0 +1,61 @@ + + + + + + +packages_quest_user_uml + + + +icepyx.quest + +icepyx.quest + + + +icepyx.quest.dataset_scripts + +icepyx.quest.dataset_scripts + + + +icepyx.quest.dataset_scripts.dataset + +icepyx.quest.dataset_scripts.dataset + + + +icepyx.quest.dataset_scripts->icepyx.quest.dataset_scripts.dataset + + + + + +icepyx.quest.dataset_scripts.argo + +icepyx.quest.dataset_scripts.argo + + + +icepyx.quest.dataset_scripts.argo->icepyx.quest.dataset_scripts.dataset + + + + + +icepyx.quest.quest + +icepyx.quest.quest + + + +icepyx.quest.quest->icepyx.quest.dataset_scripts.argo + + + + + diff --git a/doc/source/user_guide/documentation/quest.rst b/doc/source/user_guide/documentation/quest.rst index 3c86d2135..c5ae240b2 100644 --- a/doc/source/user_guide/documentation/quest.rst +++ b/doc/source/user_guide/documentation/quest.rst @@ -15,15 +15,14 @@ Constructors Quest -Attributes ----------- - -.. autosummary:: - :toctree: ../../_icepyx/ - - Methods ------- .. autosummary:: :toctree: ../../_icepyx/ + + Quest.add_icesat2 + Quest.add_argo + Quest.search_all + Quest.download_all + Quest.save_all