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 <[email protected]>
icesat2py · Mar 27, 2024 · b2dbb14 · b2dbb14
1 parent eb836ea
commit b2dbb14
Show file tree

Hide file tree

Showing 15 changed files with 532 additions and 308 deletions.
diff --git 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
@@ -95,7 +95,7 @@ Listed below are example Jupyter notebooks for working with ICESat-2 (IS2).
 
 `IS2_data_read-in <https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_data_read-in.html>`_
 
-`IS2_cloud_data_access (BETA ONLY) <https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_cloud_data_access.html>`_
+`IS2_cloud_data_access <https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_cloud_data_access.html>`_
 
 
 Citing icepyx

diff --git 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<complementary_GH_repos_label>`)
+reproducible workflow that leverages existing tools wherever possible (see :ref:`Complementary GitHub Repositories <complementary_GH_repos_label>`)
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/doc/source/user_guide/documentation/classes_quest_user_uml.svg b/doc/source/user_guide/documentation/classes_quest_user_uml.svg
diff --git a/doc/source/user_guide/documentation/icepyx-quest.rst 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 <https://github.com/icesat2py/icepyx/tree/development/doc/source/user_guide/documentation>`_.
+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
@@ -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 <https://github.com/icesat2py/icepyx/tree/development/doc/source/user_guide/documentation>`_.
 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
diff --git 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