diff --git a/.github/workflows/uml_action.yml b/.github/workflows/uml_action.yml new file mode 100644 index 000000000..cb54ae581 --- /dev/null +++ b/.github/workflows/uml_action.yml @@ -0,0 +1,32 @@ +name: Update UML diagrams +on: + workflow_dispatch: + pull_request_review: + types: [submitted] + +jobs: + diagrams: + if: github.event.review.state == 'approved' + name: Update UML diagrams + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v2 + - name: set up environment + run: | + pip install -r requirements.txt + pip install icepyx pylint + sudo apt-get install graphviz + - name: run pyreverse + run: | + pyreverse ./icepyx/core -p user_uml -o svg + pyreverse ./icepyx/core -f ALL -p dev_uml -o svg + rm ./packages_dev_uml.svg + mv ./*.svg ./doc/source/user_guide/documentation/ + - name: Commit changes + uses: EndBug/add-and-commit@v4 + with: + author_name: GitHub Action + message: "GitHub action UML generation auto-update" + add: "./doc/source/user_guide/documentation/*" + ref: git branch --show-current diff --git a/doc/source/user_guide/documentation/classes_dev_uml.svg b/doc/source/user_guide/documentation/classes_dev_uml.svg new file mode 100644 index 000000000..94bd6cb56 --- /dev/null +++ b/doc/source/user_guide/documentation/classes_dev_uml.svg @@ -0,0 +1,263 @@ + + + + + + +classes_dev_uml + + + +0 + +Earthdata + +capability_url +email +netrc : NoneType +pswd : str, NoneType +session : Session +uid + +__init__(uid, email, capability_url, pswd) +_start_session() +login() + + + +1 + +Granules + +avail : list +orderIDs : list + +__init__() +download(verbose, path, session, restart) +get_avail(CMRparams, reqparams) +place_order(CMRparams, reqparams, subsetparams, verbose, subset, session, geom_filepath) + + + +5 + +Query + +CMRparams +_CMRparams +_about_dataset +_cust_options : dict +_cycles : list +_dset : NoneType, str +_email +_end : datetime +_file_vars +_geom_filepath : NoneType +_granules +_order_vars +_readable_granule_name : list +_reqparams +_session : Session +_source : str +_spat_extent +_start : datetime +_subsetparams : NoneType +_tracks : list +_version +cycles +dataset +dataset_version +dates +end_time +extent_type : str +file_vars +granules +order_vars +reqparams +spatial_extent +start_time +tracks + +__init__(dataset, spatial_extent, date_range, start_time, end_time, version, cycles, tracks, files) +avail_granules(ids, cycles, tracks) +dataset_all_info() +dataset_summary_info() +download_granules(path, verbose, subset, restart) +earthdata_login(uid, email) +latest_version() +order_granules(verbose, subset, email) +show_custom_options(dictview) +subsetparams() +visualize_elevation() +visualize_spatial_extent() + + + +1->5 + + +_granules + + + +1->5 + + +_granules + + + +2 + +Icesat2Data + + +__init__() + + + +3 + +NsidcQueryError + +errmsg +msgtxt : str + +__init__(errmsg, msgtxt) +__str__() + + + +6 + +QueryError + + + + + + +3->6 + + + + + +4 + +Parameters + +_fmted_keys : NoneType, dict +_poss_keys : dict +_reqtype : str, NoneType +fmted_keys +partype +poss_keys + +__init__(partype, values, reqtype) +_check_valid_keys() +_get_possible_keys() +build_params() +check_req_values() +check_values() + + + +4->5 + + +_CMRparams + + + +4->5 + + +_reqparams + + + +4->5 + + +_subsetparams + + + +4->5 + + +_subsetparams + + + +7 + +Variables + +_avail : NoneType +_session : NoneType +_vartype +_version : NoneType +dataset : NoneType +source : NoneType +wanted : NoneType, dict + +__init__(vartype, avail, wanted, session, dataset, version, source) +_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) +remove(all, var_list, beam_list, keyword_list) + + + +7->5 + + +_order_vars + + + +7->5 + + +_order_vars + + + +7->5 + + +_file_vars + + + +8 + +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() +grid_bbox(binsize) +make_request(base_url, payload) +parallel_request_OA() +query_icesat2_filelist() +request_OA_data(paras) +viz_elevation() + + + diff --git a/doc/source/user_guide/documentation/classes_user_uml.svg b/doc/source/user_guide/documentation/classes_user_uml.svg new file mode 100644 index 000000000..8e51decce --- /dev/null +++ b/doc/source/user_guide/documentation/classes_user_uml.svg @@ -0,0 +1,221 @@ + + + + + + +classes_user_uml + + + +0 + +Earthdata + +capability_url +email +netrc : NoneType +pswd : NoneType, str +session : Session +uid + +login() + + + +1 + +Granules + +avail : list +orderIDs : list + +download(verbose, path, session, restart) +get_avail(CMRparams, reqparams) +place_order(CMRparams, reqparams, subsetparams, verbose, subset, session, geom_filepath) + + + +5 + +Query + +CMRparams +cycles +dataset +dataset_version +dates +end_time +extent_type : str +file_vars +granules +order_vars +reqparams +spatial_extent +start_time +tracks + +avail_granules(ids, cycles, tracks) +dataset_all_info() +dataset_summary_info() +download_granules(path, verbose, subset, restart) +earthdata_login(uid, email) +latest_version() +order_granules(verbose, subset, email) +show_custom_options(dictview) +subsetparams() +visualize_elevation() +visualize_spatial_extent() + + + +1->5 + + +_granules + + + +1->5 + + +_granules + + + +2 + +Icesat2Data + + + + + + +3 + +NsidcQueryError + +errmsg +msgtxt : str + + + + + +6 + +QueryError + + + + + + +3->6 + + + + + +4 + +Parameters + +fmted_keys +partype +poss_keys + +build_params() +check_req_values() +check_values() + + + +4->5 + + +_CMRparams + + + +4->5 + + +_reqparams + + + +4->5 + + +_subsetparams + + + +4->5 + + +_subsetparams + + + +7 + +Variables + +dataset : NoneType +source : NoneType +wanted : NoneType, dict + +append(defaults, var_list, beam_list, keyword_list) +avail(options, internal) +parse_var_list(varlist) +remove(all, var_list, beam_list, keyword_list) + + + +7->5 + + +_order_vars + + + +7->5 + + +_order_vars + + + +7->5 + + +_file_vars + + + +8 + +Visualize + +bbox : list +cycles : NoneType +date_range : NoneType +product : NoneType, str +tracks : NoneType + +generate_OA_parameters() +grid_bbox(binsize) +make_request(base_url, payload) +parallel_request_OA() +query_icesat2_filelist() +request_OA_data(paras) +viz_elevation() + + + diff --git a/doc/source/user_guide/documentation/components.rst b/doc/source/user_guide/documentation/components.rst index 3ab00051c..52982ebde 100644 --- a/doc/source/user_guide/documentation/components.rst +++ b/doc/source/user_guide/documentation/components.rst @@ -55,6 +55,14 @@ variables --------- .. automodule:: icepyx.core.variables + :members: + :undoc-members: + :show-inheritance: + +visualize +--------- + +.. automodule:: icepyx.core.visualization :members: :undoc-members: :show-inheritance: \ No newline at end of file diff --git a/doc/source/user_guide/documentation/icepyx.rst b/doc/source/user_guide/documentation/icepyx.rst index 0cb146aa0..59d7d9ff8 100644 --- a/doc/source/user_guide/documentation/icepyx.rst +++ b/doc/source/user_guide/documentation/icepyx.rst @@ -1,12 +1,20 @@ icepyx Documentation (API Reference) ==================================== -.. image:: icepyx_class_diagram.png +.. image:: packages_user_uml.svg :width: 600 - :alt: PlantUML Class Diagram illustrating the public-facing classes within icepyx, their attributes and methods, their relationships (e.g. component classes). + :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 class diagram illustrating the library's public-facing classes, their attributes and methods, and their relationships. +.. 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. +Diagrams are updated automatically after a pull request (PR) is approved and before it is merged to the development branch. .. toctree:: diff --git a/doc/source/user_guide/documentation/icepyx_architecture.wsd b/doc/source/user_guide/documentation/icepyx_architecture.wsd deleted file mode 100644 index 8b2667bac..000000000 --- a/doc/source/user_guide/documentation/icepyx_architecture.wsd +++ /dev/null @@ -1,187 +0,0 @@ -@startuml -title **icepyx Class Diagram** - -class Query { - reqparams - extent_type - subsetparams - _subsetparams - _version - file_vars - _cust_options - start_time - dates - dataset_version - granules - _granules - spatial_extent - _session - _about_dataset - _dset - _file_vars - CMRparams - _CMRparams - dataset - order_vars - _start - _order_vars - end_time - _source - subsetparams() - avail_granules() - order_granules() - download_granules() - visualize_spatial_extent() - dataset_all_info() - dataset_summary_info() - show_custom_options() - latest_version() - earthdata_login() -} -class Earthdata { - uid: string - email: string - session - pswd - capability_url - login() - _start_session() -} - -class Granules { - orderIDS - _session - files - avail - get_avail() - place_order() - download() -} - -class Variables { - _vartype - _session - dataset - wanted - _version - source - _avail - append() - avail() - remove() - _check_valid_lists() - _iter_paths() - _get_sum_varlist() -} - - -package "ICESat-2 Reference (is2ref)" { - class about_dataset{ - - } - hide about_dataset circle - - class _validate_dataset { - - } - hide _validate_dataset circle - - class _get_custom_options { - - } - hide _get_custom_options circle -} - -package "Validation (val)" { - class dset_version { - - } - hide dset_version circle - - class temporal { - - } - hide temporal circle - - class spatial { - - } - hide spatial circle -} - -'Try not using a package to help with layout (didn't change anything) -' class APIformatting.build_reqconfig_params { - -' } -' hide APIformatting.build_reqconfig_params circle - -' class APIformatting.build_CMR_params { - -' } -' hide APIformatting.build_CMR_params circle - -package "Format for API (apifmt)" { - class _fmt_temporal { - - } - hide _fmt_temporal circle - - class _fmt_spatial { - - } - hide _fmt_spatial circle - - class _fmt_var_subset_list { - - } - hide _fmt_var_subset_list circle - - class combine_params { - - } - hide combine_params circle - - class Parameters { - partype - _reqtype - _fmted_keys - poss_keys - _fmted_keys - _poss_keys - _get_possible_keys() - _check_valid_keys() - check_req_values() - check_values() - build_params() - } -} - - -Query *-left- Granules -Query *-right- Variables - -'Query -right-> about_dataset : is2ref.about_dataset -'Query -right-> _get_custom_options : is2ref._get_custom_options -'Query -right-> _validate_dataset : is2ref._validate_dataset -Query -right-> "ICESat-2 Reference (is2ref)" - -Query -right-> "Validation (val)" -'Query --> dset_version : val.dset_version -'Query --> spatial : val.spatial -'Query --> temporal: val.temporal - -Query -left-> "Format for API (apifmt)" -'Query --> build_CMR_params: apifmt.build_CMR_params -'Query --> build_reqconfig_params : apifmt.build_reqconfig_params -' Query -left-> APIformatting - -Query .down. Earthdata - -Variables -down-> _get_custom_options - -' Granules -[hidden]- APIformatting -' Earthdata -[hidden]- APIformatting -Granules -[hidden]- "Format for API (apifmt)" -Earthdata -[hidden]- "Format for API (apifmt)" -"ICESat-2 Reference (is2ref)" -[hidden]- "Validation (val)" -@enduml \ No newline at end of file diff --git a/doc/source/user_guide/documentation/icepyx_architecture_user.wsd b/doc/source/user_guide/documentation/icepyx_architecture_user.wsd deleted file mode 100644 index 80e57bcf8..000000000 --- a/doc/source/user_guide/documentation/icepyx_architecture_user.wsd +++ /dev/null @@ -1,187 +0,0 @@ -@startuml -title **icepyx Class Diagram** - -class Query { - reqparams - extent_type - subsetparams - ' _subsetparams - ' _version - file_vars - ' _cust_options - start_time - dates - dataset_version - granules - ' _granules - spatial_extent - ' _session - ' _about_dataset - ' _dset - ' _file_vars - CMRparams - ' _CMRparams - dataset - order_vars - ' _start - ' _order_vars - end_time - ' _source - subsetparams() - avail_granules() - order_granules() - download_granules() - visualize_spatial_extent() - dataset_all_info() - dataset_summary_info() - show_custom_options() - latest_version() - earthdata_login() -} -class Earthdata { - uid: string - email: string - session - pswd - capability_url - login() -' _start_session() -} - -class Granules { - orderIDS - ' _session - ' files - avail - get_avail() - place_order() - download() -} - -class Variables { -' _vartype -' _session - dataset - wanted -' _version - source -' _avail - append() - avail() - remove() -' _check_valid_lists() -' _iter_paths() -' _get_sum_varlist() -} - - -package "ICESat-2 Reference (is2ref)" { - class about_dataset{ - - } - hide about_dataset circle - - ' class _validate_dataset { - - ' } - ' hide _validate_dataset circle - - ' class _get_custom_options { - - ' } - ' hide _get_custom_options circle -} - -package "Validation (val)" { - class dset_version { - - } - hide dset_version circle - - class temporal { - - } - hide temporal circle - - class spatial { - - } - hide spatial circle -} - -'Try not using a package to help with layout (didn't change anything) -' class APIformatting.build_reqconfig_params { - -' } -' hide APIformatting.build_reqconfig_params circle - -' class APIformatting.build_CMR_params { - -' } -' hide APIformatting.build_CMR_params circle - -package "Format for API (apifmt)" { - ' class _fmt_temporal { - - ' } - ' hide _fmt_temporal circle - - ' class _fmt_spatial { - - ' } - ' hide _fmt_spatial circle - - ' class _fmt_var_subset_list { - - ' } - ' hide _fmt_var_subset_list circle - - class combine_params { - - } - hide combine_params circle - - class Parameters { - partype - ' _reqtype - ' _fmted_keys - poss_keys - ' _fmted_keys - ' _poss_keys - ' _get_possible_keys() - ' _check_valid_keys() - check_req_values() - check_values() - build_params() - } -} - - -Query *-left- Granules -Query *-right- Variables - -''Query -right-> about_dataset : is2ref.about_dataset -''Query -right-> _get_custom_options : is2ref._get_custom_options -''Query -right-> _validate_dataset : is2ref._validate_dataset -Query -right-> "ICESat-2 Reference (is2ref)" - -Query -right-> "Validation (val)" -''Query --> dset_version : val.dset_version -''Query --> spatial : val.spatial -''Query --> temporal: val.temporal - -Query -left-> "Format for API (apifmt)" -''Query --> build_CMR_params: apifmt.build_CMR_params -''Query --> build_reqconfig_params : apifmt.build_reqconfig_params -'' Query -left-> APIformatting - -Query .down. Earthdata - -' Variables -down-> _get_custom_options - -'' Granules -[hidden]- APIformatting -'' Earthdata -[hidden]- APIformatting -Granules -[hidden]- "Format for API (apifmt)" -Earthdata -[hidden]- "Format for API (apifmt)" -"ICESat-2 Reference (is2ref)" -[hidden]- "Validation (val)" -@enduml \ No newline at end of file diff --git a/doc/source/user_guide/documentation/icepyx_class_diagram.png b/doc/source/user_guide/documentation/icepyx_class_diagram.png deleted file mode 100644 index a98b53605..000000000 Binary files a/doc/source/user_guide/documentation/icepyx_class_diagram.png and /dev/null differ diff --git a/doc/source/user_guide/documentation/icepyx_class_diagram_full.png b/doc/source/user_guide/documentation/icepyx_class_diagram_full.png deleted file mode 100644 index 84efb7c7a..000000000 Binary files a/doc/source/user_guide/documentation/icepyx_class_diagram_full.png and /dev/null differ diff --git a/doc/source/user_guide/documentation/packages_user_uml.svg b/doc/source/user_guide/documentation/packages_user_uml.svg new file mode 100644 index 000000000..170e047f4 --- /dev/null +++ b/doc/source/user_guide/documentation/packages_user_uml.svg @@ -0,0 +1,109 @@ + + + + + + +packages_user_uml + + + +0 + +icepyx.core + + + +1 + +icepyx.core.APIformatting + + + +2 + +icepyx.core.Earthdata + + + +3 + +icepyx.core.exceptions + + + +4 + +icepyx.core.geospatial + + + +5 + +icepyx.core.granules + + + +6 + +icepyx.core.icesat2data + + + +7 + +icepyx.core.is2ref + + + +8 + +icepyx.core.query + + + +8->2 + + + + + +8->5 + + + + + +10 + +icepyx.core.variables + + + +8->10 + + + + + +11 + +icepyx.core.visualization + + + +8->11 + + + + + +9 + +icepyx.core.validate_inputs + + +