Update documentation styling for easier navigation (#624)

xCDAT · Mar 20, 2024 · b86f0ce · b86f0ce
1 parent d0e33aa
commit b86f0ce
Show file tree

Hide file tree

Showing 32 changed files with 525 additions and 232 deletions.
diff --git a/.gitignore b/.gitignore
@@ -116,3 +116,8 @@ conda-build/
 
 # Ad-hoc QA
 qa/
+
+# Sphinx generated .txt files
+notebook-examples.txt
+team-panel.txt
+demos.txt
diff --git a/AUTHORS.rst b/AUTHORS.rst
diff --git a/README.rst b/README.rst
@@ -215,12 +215,21 @@ Xarray and Xarray usage in climate science!
 - `Pangeo Forum <https://foundations.projectpythia.org/core/xarray.html>`_
 - `Project Pythia <https://foundations.projectpythia.org/core/xarray.html>`_
 
-Acknowledgement
----------------
+Projects Using xCDAT
+--------------------
 
-Huge thank you to all of the xCDAT `contributors`_!
+xCDAT is actively being integrated as a core component of the `Program for Climate Model
+Diagnosis and Intercomparison (PCMDI) Metrics Package`_ and the `Energy Exascale Earth
+System Model Diagnostics (E3SM) Package`_. xCDAT is also included in the `E3SM Unified
+Anaconda Environment`_ that is deployed on various U.S. Department of Energy
+supercomputers to run E3SM software tools.
+
+.. _Program for Climate Model Diagnosis and Intercomparison (PCMDI) Metrics Package: https://pcmdi.github.io/pcmdi_metrics/
+.. _Energy Exascale Earth System Model Diagnostics (E3SM) Package: https://e3sm-project.github.io/e3sm_diags/_build/html/main/index.html
+.. _E3SM Unified Anaconda Environment: https://e3sm.org/resources/tools/other-tools/e3sm-unified-environment/
 
-.. _contributors: https://github.com/xCDAT/xcdat/graphs/contributors
+Acknowledgement
+---------------
 
 xCDAT is jointly developed by scientists and developers from the Energy Exascale
 Earth System Model (`E3SM`_) Project and Program for Climate Model Diagnosis and
@@ -241,18 +250,14 @@ Environmental Research (`BER`_) within the `Department of Energy`_'s `Office of
 .. _Department of Energy: https://www.energy.gov/
 .. _Office of Science: https://science.osti.gov/
 
-Projects Using xCDAT
---------------------
+Contributors
+------------
 
-xCDAT is actively being integrated as a core component of the `Program for Climate Model
-Diagnosis and Intercomparison (PCMDI) Metrics Package`_ and the `Energy Exascale Earth
-System Model Diagnostics (E3SM) Package`_. xCDAT is also included in the `E3SM Unified
-Anaconda Environment`_ that is deployed on various U.S. Department of Energy
-supercomputers to run E3SM software tools.
+Thank you to all of our contributors!
 
-.. _Program for Climate Model Diagnosis and Intercomparison (PCMDI) Metrics Package: https://pcmdi.github.io/pcmdi_metrics/
-.. _Energy Exascale Earth System Model Diagnostics (E3SM) Package: https://e3sm-project.github.io/e3sm_diags/_build/html/main/index.html
-.. _E3SM Unified Anaconda Environment: https://e3sm.org/resources/tools/other-tools/e3sm-unified-environment/
+.. image:: https://contrib.rocks/image?repo=xCDAT/xcdat
+  :alt: xCDAT contributors
+  :target: https://github.com/xCDAT/xcdat/graphs/contributors
 
 License
 -------

diff --git a/conda-env/dev.yml b/conda-env/dev.yml
@@ -29,6 +29,7 @@ dependencies:
     - sphinx-book-theme
     - sphinx-copybutton
     - nbsphinx
+    - sphinx-design
     - pandoc
     - ipython # Required for nbsphinx syntax highlighting
     - gsw-xarray # Required for vertical regridding example

diff --git a/docs/_static/icons/book.svg b/docs/_static/icons/book.svg
diff --git a/docs/_static/icons/play.svg b/docs/_static/icons/play.svg
diff --git a/docs/_static/icons/plot.svg b/docs/_static/icons/plot.svg
diff --git a/docs/_static/icons/wrench.svg b/docs/_static/icons/wrench.svg
diff --git a/docs/_static/style.css b/docs/_static/style.css
@@ -0,0 +1,9 @@
+/* Main index page overview cards */
+
+.sd-card-img-top {
+    width: 33% !important;
+    display: block;
+    margin-left: auto;
+    margin-right: auto;
+    margin-top: 10px;
+}
diff --git a/docs/_static/thumbnails/ams-logo.jpg b/docs/_static/thumbnails/ams-logo.jpg
diff --git a/docs/_static/thumbnails/climatology-and-departures.png b/docs/_static/thumbnails/climatology-and-departures.png
diff --git a/docs/_static/thumbnails/esgf2-logo.png b/docs/_static/thumbnails/esgf2-logo.png
diff --git a/docs/_static/thumbnails/llnl-logo.png b/docs/_static/thumbnails/llnl-logo.png
diff --git a/docs/_static/thumbnails/regridding-horizontal.png b/docs/_static/thumbnails/regridding-horizontal.png
diff --git a/docs/_static/thumbnails/regridding-vertical.png b/docs/_static/thumbnails/regridding-vertical.png
diff --git a/docs/_static/thumbnails/spatial-avg.png b/docs/_static/thumbnails/spatial-avg.png
diff --git a/docs/_static/thumbnails/temporal-average.png b/docs/_static/thumbnails/temporal-average.png
diff --git a/docs/authors.rst b/docs/authors.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -18,11 +18,16 @@
 # absolute, like shown here.
 #
 import os
+import pathlib
 import sys
 from pathlib import Path
 from typing import Dict
+from textwrap import dedent, indent
 
 import sphinx_autosummary_accessors
+import yaml
+from sphinx.application import Sphinx
+from sphinx.util import logging
 
 # A workaround that sets the "ESMFMKFILE" env variable for the Read The Docs
 # build to work. Read The Docs does not activate the conda environment which
@@ -34,6 +39,8 @@
 sys.path.insert(0, os.path.abspath(".."))  # noqa: I001, I003
 import xcdat  # noqa: I001, E402
 
+LOGGER = logging.getLogger("conf")
+
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -50,6 +57,7 @@
     "sphinx_autosummary_accessors",
     "sphinx_copybutton",
     "nbsphinx",
+    "sphinx_design",
 ]
 
 # autosummary and autodoc configurations
@@ -160,7 +168,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-
+html_css_files = ["style.css"]
 
 # -- Options for HTMLHelp output ---------------------------------------
 
@@ -224,5 +232,109 @@ def html_page_context(app, pagename, templatename, context, doctree):
         context["theme_use_edit_page_button"] = False
 
 
-def setup(app):
+def update_team(app: Sphinx):
+    """Update the team members list."""
+
+    LOGGER.info("Updating team members page...")
+
+    team = yaml.safe_load(pathlib.Path(app.srcdir, "team.yml").read_bytes())
+    items = []
+    for member in team:
+        item = f"""
+        .. grid-item-card::
+            :text-align: center
+            :link: https://github.com/{member['gh_login']}
+
+            .. image:: {member['avatar']}
+                :alt: {member['name']}
+            +++
+            {member['name']}
+        """
+        items.append(item)
+
+    items_md = indent(dedent("\n".join(items)), prefix="    ")
+
+    markdown = f"""
+.. grid:: 1 2 3 3
+    :gutter: 2
+
+    {items_md}
+    """
+
+    pathlib.Path(app.srcdir, "team-panel.txt").write_text(markdown)
+    LOGGER.info("Team members page updated.")
+
+
+def update_gallery(app: Sphinx):
+    """Update the gallery of examples notebooks."""
+
+    LOGGER.info("Updating gallery page...")
+
+    notebooks = yaml.safe_load(pathlib.Path(app.srcdir, "gallery.yml").read_bytes())
+
+    items = [
+        f"""
+         .. grid-item-card::
+            :text-align: center
+            :link: {item['path']}
+
+            .. image:: {item['thumbnail']}
+                :alt: {item['title']}
+            +++
+            {item['title']}
+            """
+        for item in notebooks
+    ]
+
+    items_md = indent(dedent("\n".join(items)), prefix="    ")
+    markdown = f"""
+.. grid:: 1 2 3 3
+    :gutter: 2
+
+    {items_md}
+    """
+
+    pathlib.Path(app.srcdir, "notebook-examples.txt").write_text(markdown)
+
+    LOGGER.info("Gallery page updated.")
+
+
+def update_demos(app: Sphinx):
+    """Update the demos page."""
+
+    LOGGER.info("Updating demos page...")
+
+    links = yaml.safe_load(pathlib.Path(app.srcdir, "demos.yml").read_bytes())
+
+    items = [
+        f"""
+         .. grid-item-card::
+            :text-align: center
+            :link: {item['path']}
+
+            .. image:: {item['thumbnail']}
+                :alt: {item['title']}
+            +++
+            {item['title']}
+            """
+        for item in links
+    ]
+
+    items_md = indent(dedent("\n".join(items)), prefix="    ")
+    markdown = f"""
+.. grid:: 1 2 3 3
+    :gutter: 2
+
+    {items_md}
+    """
+
+    pathlib.Path(app.srcdir, "demos.txt").write_text(markdown)
+
+    LOGGER.info("Demos page updated.")
+
+
+def setup(app: Sphinx):
     app.connect("html-page-context", html_page_context)
+    app.connect("builder-inited", update_team)
+    app.connect("builder-inited", update_gallery)
+    app.connect("builder-inited", update_demos)
diff --git a/docs/demos.rst b/docs/demos.rst
@@ -3,10 +3,12 @@ Presentations and Demos
 
 This page includes relevant xCDAT presentations, demos, and papers.
 
+.. include:: demos.txt
+
 .. toctree::
     :maxdepth: 2
     :hidden:
 
     AMS 2023 Abstract <https://ams.confex.com/ams/103ANNUAL/meetingapp.cgi/Paper/412648>
     demos/1-25-23-cwss-seminar/introduction-to-xcdat.ipynb
-    A Gentle Introduction to xCDAT (Xarray Climate Data Analysis Tools) - Video introduction <https://youtu.be/sJpQ9vKDKa8?feature=shared>
+    ESGF2 - A Gentle Introduction to xCDAT (video introduction) <https://youtu.be/sJpQ9vKDKa8?feature=shared>
diff --git a/docs/demos.yml b/docs/demos.yml
@@ -0,0 +1,11 @@
+- title: AMS 2023 Abstract
+  path: https://ams.confex.com/ams/103ANNUAL/meetingapp.cgi/Paper/412648
+  thumbnail: _static/thumbnails/ams-logo.jpg
+
+- title: LLNL Climate and Weather Seminar Series (01/25/2023) - A Gentle Introduction to xCDAT
+  path: demos/1-25-23-cwss-seminar/introduction-to-xcdat.ipynb
+  thumbnail: _static/thumbnails/llnl-logo.png
+
+- title: ESGF2 - A Gentle Introduction to xCDAT (video introduction)
+  path: https://youtu.be/sJpQ9vKDKa8?feature=shared
+  thumbnail: _static/thumbnails/esgf2-logo.png
diff --git a/docs/examples/general-utilities.ipynb b/docs/examples/general-utilities.ipynb
@@ -4564,7 +4564,7 @@
     "\n",
     "Helpful knowledge:\n",
     "\n",
-    "- This API uses `cf_xarray` to interpret CF axis names and coordinate names in the xarray object attributes. Refer to [Metadata Interpretation](../faqs.rst) for more information.\n",
+    "- This API uses `cf_xarray` to interpret CF axis names and coordinate names in the xarray object attributes. Refer to [Metadata Interpretation](../getting-started-guide/faqs.rst) for more information.\n",
     "\n",
     "Xarray documentation on coordinates ([source](https://docs.xarray.dev/en/stable/user-guide/data-structures.html#coordinates)):\n",
     "\n",

diff --git a/docs/gallery.rst b/docs/gallery.rst
@@ -1,9 +1,9 @@
 Gallery
 =======
 
-This gallery demonstrates how to use some of the features in ``xcdat``. Contributions are highly welcomed and appreciated.
-Please checkout the :doc:`contributing` guide.
+This gallery demonstrates how to use some of the features in ``xcdat``. Contributions are highly welcomed and appreciated. Please checkout the :doc:`contributing` guide.
 
+.. include:: notebook-examples.txt
 
 .. toctree::
     :maxdepth: 2

diff --git a/docs/gallery.yml b/docs/gallery.yml
@@ -0,0 +1,27 @@
+- title: A Gentle Introduction to xCDAT (Xarray Climate Data Analysis Tools)
+  path: examples/introduction-to-xcdat.ipynb
+  thumbnail: _static/xcdat-logo.png
+
+- title: General Dataset Utilities
+  path: examples/general-utilities.ipynb
+  thumbnail: _static/dataset-diagram.webp
+
+- title: Calculate Geospatial Weighted Averages from Monthly Time Series
+  path: examples/spatial-average.ipynb
+  thumbnail: _static/thumbnails/spatial-avg.png
+
+- title: Calculate Time Averages from Time Series Data
+  path: examples/temporal-average.ipynb
+  thumbnail: _static/thumbnails/temporal-average.png
+
+- title: Calculate Climatology and Departures from Time Series Data
+  path: examples/climatology-and-departures.ipynb
+  thumbnail: _static/thumbnails/climatology-and-departures.png
+
+- title: Horizontal Regridding
+  path: examples/regridding-horizontal.ipynb
+  thumbnail: _static/thumbnails/regridding-horizontal.png
+
+- title: Vertical Regridding
+  path: examples/regridding-vertical.ipynb
+  thumbnail: _static/thumbnails/regridding-vertical.png
diff --git a/docs/faqs.rst → docs/getting-started-guide/faqs.rst b/docs/faqs.rst → docs/getting-started-guide/faqs.rst
diff --git a/docs/getting-started-hpc-jupyter.rst → ...ted-guide/getting-started-hpc-jupyter.rst b/docs/getting-started-hpc-jupyter.rst → ...ted-guide/getting-started-hpc-jupyter.rst
@@ -19,9 +19,9 @@ Setting up your xCDAT environment
 Ensure ``conda`` is installed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Generally, the instructions from `getting started guide <getting-started.rst>`_ can also
-be followed for HPC machines. This guide covers installing Miniconda3 and creating
-a conda environment with the ``xcdat`` package.
+Generally, the installation instructions from the `Installation <../installation.rst>`_
+page can also be followed for HPC machines. This guide covers installing Miniconda3 and
+creating a conda environment with the ``xcdat`` package.
 
 Before installing Miniconda3, you should consult your HPC documentation to see if
 ``conda`` is already available; in some cases, ``python`` and ``conda`` may be
@@ -101,4 +101,4 @@ kernel. You should then be able to use your ``xcdat`` environment on Jupyter.
 
 |image0|
 
-.. |image0| image:: _static/jupyter-launcher-example.png
+.. |image0| image:: ../_static/jupyter-launcher-example.png
diff --git a/docs/getting-started-guide/index.rst b/docs/getting-started-guide/index.rst
@@ -0,0 +1,14 @@
+################
+Getting Started
+################
+
+The getting started guide aims to get you using xCDAT productively as quickly as possible.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   Project Overview <overview>
+   Installation <installation>
+   xCDAT on HPC / Jupyter <getting-started-hpc-jupyter>
+   faqs