ENH: Migrate to pydata theme so version switcher can be used.

docs/requirements.txt

@@ -4,11 +4,13 @@ ipywidgets
 jupyter_client
 nbsphinx
 Pillow
+pydata-sphinx-theme
 sphinx
 sphinx-autoapi
-sphinx-book-theme
 sphinx-copybutton
 sphinx-design
+sphinx-favicon
 sphinx-gallery
+sphinx-togglebutton
 sphinxcontrib-bibtex
 sphinxext-opengraph

docs/source/autoapi/pygeohydro/nfhl/index.rst

@@ -107,7 +107,7 @@ Module Contents
    .. method:: bysql(sql_clause, return_m=False, return_geom=True)
 
       Get features using a valid SQL 92 WHERE clause.
-      
+
 
    .. py:property:: valid_services
       :type: dict[str, str]

docs/source/autoapi/pygeohydro/pygeohydro/index.rst

@@ -34,7 +34,7 @@ Module Contents
    .. method:: bysql(sql_clause, return_m=False, return_geom=True)
 
       Get features using a valid SQL 92 WHERE clause.
-      
+
 
    :Parameters: **data_type** (:class:`str`, *optional*) -- Type of the survey data to retrieve, defaults to ``points``.
                 Note that the ``points`` data type gets the best available point

docs/source/autoapi/pygeohydro/stnfloodevents/index.rst

@@ -115,7 +115,7 @@ Module Contents
 
          :meth:`~get_all_data`
              Retrieves all data for a given data type.
-         
+
          :meth:`~get_filtered_data`
              Retrieves filtered data for a given data type.
 
@@ -153,7 +153,7 @@ Module Contents
 
          :meth:`~get_filtered_data`
              Retrieves filtered data for a given data type.
-         
+
          :meth:`~data_dictionary`
              Retrieves the data dictionary for a given data type.
 
@@ -217,7 +217,7 @@ Module Contents
 
          :meth:`~get_all_data`
              Retrieves all data for a given data type.
-         
+
          :meth:`~data_dictionary`
              Retrieves the data dictionary for a given data type.
 

docs/source/autoapi/pynhd/pynhd/index.rst

@@ -47,7 +47,7 @@ Module Contents
    .. method:: bysql(sql_clause, return_m=False, return_geom=True)
 
       Get features using a valid SQL 92 WHERE clause.
-      
+
 
 
 .. py:class:: NHD(layer, outfields = '*', crs = 4326)
@@ -93,7 +93,7 @@ Module Contents
    .. method:: bysql(sql_clause, return_m=False, return_geom=True)
 
       Get features using a valid SQL 92 WHERE clause.
-      
+
 
 
 .. py:class:: NHDPlusHR(layer, outfields = '*', crs = 4326)
@@ -136,7 +136,7 @@ Module Contents
    .. method:: bysql(sql_clause, return_m=False, return_geom=True)
 
       Get features using a valid SQL 92 WHERE clause.
-      
+
 
 
 .. py:class:: NLDI

docs/source/conf.py

@@ -1,4 +1,5 @@
 import datetime
+import os
 import urllib.request
 import json
 import tomllib as tomli
@@ -52,6 +53,8 @@
     "sphinx_copybutton",
     "sphinxcontrib.bibtex",
     "sphinx_design",
+    "sphinx_togglebutton",
+    "sphinx_favicon",
 ]
 
 bibtex_bibfiles = ['refs.bib']
@@ -60,7 +63,6 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "xarray": ("https://xarray.pydata.org/en/stable/", None),
-    "dask": ("https://docs.dask.org/en/latest/", None),
     "geopandas": ("https://geopandas.org/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
@@ -206,37 +208,133 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "tests", ".ipynb_checkpoints", "**.github", "**examples/README.md"]
 
 # sphinx_book_theme configurations
-html_theme = "sphinx_book_theme"
+html_theme = "pydata_sphinx_theme"
+# html_theme = "sphinx_book_theme"
 html_title = ""
 
+# logo
+html_last_updated_fmt = today_fmt
+html_logo = "_static/hyriver_logo_text.svg"
+html_favicon = "_static/favicon.ico"
+
 html_context = {
     "github_user": "cheginit",
     "github_repo": "hyriver.github.io",
     "github_version": "main",
     "doc_path": "docs",
 }
 html_baseurl = "https://docs.hyriver.io"
+# html_theme_options = {
+#     "repository_url": "https://github.com/hyriver/hyriver.github.io",
+#     "repository_branch": "main",
+#     "path_to_docs": "docs",
+#     "launch_buttons": {
+#         "binderhub_url": "https://mybinder.org/v2/gh/hyriver/HyRiver-examples/main?urlpath=lab/tree/notebooks",
+#         "notebook_interface": "jupyterlab",
+#     },
+#     "use_edit_page_button": True,
+#     "use_repository_button": True,
+#     "use_download_button": False,
+#     "use_issues_button": True,
+#     "home_page_in_toc": True,
+#     "navigation_with_keys": False,
+# }
+
+json_url = "https://docs.hyriver.io/_static/switcher.json"
+# Define the version we use for matching in the version switcher.
+version_match = os.environ.get("READTHEDOCS_VERSION")
+# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+# If it is an integer, we're in a PR build and the version isn't correct.
+# If it's "latest" → change to "dev" (that's what we want the switcher to call it)
+if not version_match or version_match.isdigit() or version_match == "latest":
+    # For local development, infer the version to match from the package.
+    if "dev" in release or "rc" in release:
+        version_match = "dev"
+        # We want to keep the relative reference if we are in dev mode
+        # but we want the whole url if we are effectively in a released version
+        json_url = "_static/switcher.json"
+    else:
+        version_match = f"v{release}"
+elif version_match == "stable":
+    version_match = f"v{release}"
 html_theme_options = {
-    "repository_url": "https://github.com/hyriver/hyriver.github.io",
-    "repository_branch": "main",
-    "path_to_docs": "docs",
-    "launch_buttons": {
-        "binderhub_url": "https://mybinder.org/v2/gh/hyriver/HyRiver-examples/main?urlpath=lab/tree/notebooks",
-        "notebook_interface": "jupyterlab",
+    "header_links_before_dropdown": 4,
+    "icon_links": [
+        {
+            "name": "Twitter",
+            "url": "https://twitter.com/ContactHyRiver",
+            "icon": "fa-brands fa-twitter",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/hyriver/hyriver.github.io",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+    # alternative way to set twitter and github header icons
+    # "github_url": "https://github.com/pydata/pydata-sphinx-theme",
+    # "twitter_url": "https://twitter.com/PyData",
+    "logo": {
+        "text": "",
+        "image_dark": "_static/hyriver_logo_text.svg",
     },
     "use_edit_page_button": True,
-    "use_repository_button": True,
-    "use_download_button": False,
-    "use_issues_button": True,
-    "home_page_in_toc": True,
+    "show_toc_level": 1,
+    "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
+    # "show_nav_level": 2,
+    # "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
+    "show_version_warning_banner": True,
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    # "navbar_start": ["navbar-logo"],
+    # "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    # "navbar_persistent": ["search-button"],
+    # "primary_sidebar_end": ["custom-template", "sidebar-ethical-ads"],
+    # "article_footer_items": ["test", "test"],
+    # "content_footer_items": ["test", "test"],
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    "secondary_sidebar_items": {
+        "**/*": ["page-toc", "edit-this-page", "sourcelink"],
+        "examples/no-sidebar": [],
+    },
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
+    # "back_to_top_button": False,
     "navigation_with_keys": False,
 }
 
-# logo
-html_last_updated_fmt = today_fmt
-html_logo = "_static/hyriver_logo_text.svg"
-html_favicon = "_static/favicon.ico"
+html_sidebars = {
+    "contributing": [],
+    "authors": [],
+    "license": [],
+    "readme/*": [],
+}
+
 htmlhelp_basename = "HyRiverdoc"
+html_sourcelink_suffix = ""
+html_last_updated_fmt = ""  # to reveal the build date in the pages meta
+
+# -- favicon options ---------------------------------------------------------
+
+# see https://sphinx-favicon.readthedocs.io for more information about the
+# sphinx-favicon extension
+favicons = [
+    # generic icons compatible with most browsers
+    # "favicon-32x32.png",
+    # "favicon-16x16.png",
+    {"rel": "shortcut icon", "sizes": "any", "href": "favicon.ico"},
+    # # chrome specific
+    # "android-chrome-192x192.png",
+    # # apple icons
+    # {"rel": "mask-icon", "color": "#459db9", "href": "safari-pinned-tab.svg"},
+    # {"rel": "apple-touch-icon", "href": "apple-touch-icon.png"},
+    # # msapplications
+    # {"name": "msapplication-TileColor", "content": "#459db9"},
+    # {"name": "theme-color", "content": "#ffffff"},
+    # {"name": "msapplication-TileImage", "content": "mstile-150x150.png"},
+]
 
 # configuration for opengraph
 description = " ".join(
@@ -425,7 +523,7 @@ def resize_thumbnails(app: Sphinx)-> None:
                 # Calculate the new size, maintaining aspect ratio
                 ratio = min(target_size[0] / img.width, target_size[1] / img.height)
                 new_size = (int(img.width * ratio), int(img.height * ratio))
-                
+
                 # Resize the image with the new size
                 img = img.resize(new_size, Image.Resampling.LANCZOS)
 

docs/source/getting_started.rst

@@ -20,6 +20,103 @@ Some major capabilities of HyRiver are as follows:
 * A URL inventory for some popular (and tested) web services.
 * Some utilities for manipulating the obtained data and their visualization.
 
+
+Software Stack
+--------------
+
+.. grid::
+    :gutter: 3
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pynhd.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyNHD
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pygeohydro.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyGeoHydro
+
+    .. grid-item-card::
+
+        .. button-link:: readme/py3dep.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            Py3DEP
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pydaymet.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyDaymet
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pygridmet.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyGridMET
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pynldas2.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyNLDAS2
+
+    .. grid-item-card::
+
+        .. button-link:: readme/hydrosignatures.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            HydroSignatures
+
+    .. grid-item-card::
+
+        .. button-link:: readme/async-retriever.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            AsyncRetriever
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pygeoogc.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyGeoOGC
+
+    .. grid-item-card::
+
+        .. button-link:: readme/pygeoutils.html
+            :click-parent:
+            :ref-type: ref
+            :align: center
+
+            PyGeoUtils
+
 Installation
 ------------
 
@@ -64,3 +161,18 @@ the performance of some computations. Installing ``pyogrio`` is highly recommend
 for improving the performance of working with vector data. For NHDPlus, ``py7zr``
 and ``pyogrio`` are required dependencies. For retrieving soil
 data, you should install ``planetary-computer`` and ``pystac-client``.
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    PyNHD <readme/pynhd>
+    PyGeoHydro <readme/pygeohydro>
+    Py3DEP <readme/py3dep>
+    PyDaymet <readme/pydaymet>
+    PyGridMET <readme/pygridmet>
+    PyNLDAS2 <readme/pynldas2>
+    HydroSignatures <readme/hydrosignatures>
+    AsyncRetriever<readme/async-retriever>
+    PyGeoOGC <readme/pygeoogc>
+    PyGeoUtils <readme/pygeoutils>

docs/source/index.rst

@@ -221,7 +221,6 @@ If you use any of HyRiver packages in your research, we appreciate citations:
     :hidden:
 
     getting_started
-    readmes
     examples
 
 .. toctree::