Add tutorial gallery and ICESat-2 resources

Merge pull request #1 from ICESAT-2HackWeek/gallery

.gitignore

@@ -14,6 +14,7 @@ cookiecutter.json
 /book/_build/html/assets
 ## Temporary files created by build scripts
 /team/team.yaml
+/book/reference/gallery.txt
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

book/_config.yml

@@ -67,6 +67,8 @@ sphinx:
         .py:
             - jupytext.reads
             - fmt: py:percent
+  local_extensions:
+    build_gallery: "_ext"
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository

book/_ext/build_gallery.py

@@ -0,0 +1,95 @@
+# from https://github.com/executablebooks/meta/blob/b627cdf10477e4bdf651bc86043a3fca1cc8d130/docs/conf.py
+
+from pathlib import Path
+import random
+from textwrap import dedent
+from urllib.parse import urlparse
+
+import yaml
+
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.typing import ExtensionMetadata
+
+LOGGER = logging.getLogger("conf")
+
+def build_gallery(app: Sphinx):
+    # Build the gallery file
+    LOGGER.info("building gallery...")
+    grid_items = []
+    projects = yaml.safe_load((Path(app.srcdir) / "reference/gallery.yml").read_text())
+    random.shuffle(projects)
+    for item in projects:
+        if not item.get("image"):
+            item["image"] = "https://jupyterbook.org/_images/logo-square.svg"
+
+        repo_text = ""
+        star_text = ""
+
+        if item["repository"]:
+            repo_text = f'{{bdg-link-secondary}}`repo <{item["repository"]}>`'
+
+            try:
+                url = urlparse(item["repository"])
+                if url.netloc == "github.com":
+                    _, org, repo = url.path.rstrip("/").split("/")
+                    star_text = f"[![GitHub Repo stars](https://img.shields.io/github/stars/{org}/{repo}?style=social)]({item['repository']})"
+            except Exception as error:
+                pass
+
+        grid_items.append(
+            f"""\
+        `````{{grid-item-card}} {" ".join(item["name"].split())}
+        :text-align: center
+
+        <img src="{item["image"]}" alt="logo" loading="lazy" style="max-width: 100%; max-height: 200px; margin-top: 1rem;" />
+
+        +++
+        ````{{grid}} 2 2 2 2
+        :margin: 0 0 0 0
+        :padding: 0 0 0 0
+        :gutter: 1
+
+        ```{{grid-item}}
+        :child-direction: row
+        :child-align: start
+        :class: sd-fs-5
+
+        {{bdg-link-secondary}}`website <{item["website"]}>`
+        {repo_text}
+        ```
+        ```{{grid-item}}
+        :child-direction: row
+        :child-align: end
+
+        {star_text}
+        ```
+        ````
+        `````
+        """
+        )
+    grid_items = "\n".join(grid_items)
+
+# :column: text-center col-6 col-lg-4
+# :card: +my-2
+# :img-top-cls: w-75 m-auto p-2
+# :body: d-none
+
+    panels = f"""
+``````{{grid}} 1 2 3 3
+:gutter: 1 1 2 2
+
+{dedent(grid_items)}
+``````
+    """
+    (Path(app.srcdir) / "reference/gallery.txt").write_text(panels)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.connect('builder-inited', build_gallery)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

book/_toc.yml

@@ -32,5 +32,6 @@ parts:
   chapters:
     - file: reference/glossary
     - file: reference/bibliography
+    - file: reference/IS2-resources
     - file: reference/questions
 

book/reference/IS2-resources.md

@@ -0,0 +1,16 @@
+# ICESat-2 Resources
+
+A large number of resources exist for helping you get and work with ICESat-2 data.
+These range from packages and tutorials created by NSIDC, the DAAC that manages ICESat-2 data,
+to community created libraries (such as [icepyx](https://icepyx.readthedocs.io/en/latest/) and [SlideRule](https://slideruleearth.io/)),
+to individual GitHub repositories created by researchers using ICESat-2 data in their work.
+
+## Lists of Resources
+Both [icepyx](https://icepyx.readthedocs.io/en/latest/community/resources.html) and [NSIDC](https://nsidc.org/data/icesat-2/tools) already have compiled lists of resources for obtaining and working with ICESat-2 data.
+We encourage you to check them out, but have not recreated them here so you can always find the latest and greatest.
+
+## Gallery of Tutorials
+The Organizing Team (OT) has compiled this gallery of their favorite tutorials and tools for getting and utilizing ICESat-2 data to help you find great example workflows from across disciplines.
+
+```{include} gallery.txt
+```

book/reference/gallery.yml

@@ -0,0 +1,17 @@
+- name: Data access with earthaccess
+  website: https://earthaccess.readthedocs.io/en/latest/tutorials/file-access/
+  repository: https://github.com/nsidc/earthaccess
+  image: 
+- name: Data access with icepyx
+  website: https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_data_access.html
+  repository: https://github.com/icesat2py/icepyx
+  image: https://icepyx.readthedocs.io/en/latest/_static/icepyx_v2_oval_orig_nobackgr.png
+- name: Data access with SlideRule
+  website: https://slideruleearth.io/rtd/getting_started/Examples.html
+  repository: https://github.com/SlideRuleEarth/sliderule
+  image: https://avatars.githubusercontent.com/u/63428847?s=200&v=4
+- name: Download and plot ATL08
+  website: https://nasa-openscapes.github.io/2023-ssc/tutorials/data-access/icepyx.html
+  repository: https://github.com/NASA-Openscapes/2023-ssc
+  image: https://raw.githubusercontent.com/NASA-Openscapes/media/main/images/scc/espacio-logo.png
+

conda/environment.yml

@@ -8,7 +8,7 @@ channels:
   - conda-forge
 dependencies:
   - ipyleaflet
-  - jupyter-book<2
+  - jupyter-book
   - jupyter-resource-usage
   - jupyterhub-singleuser
   - jupyterlab