diff --git a/docs/requirements.txt b/docs/requirements.txt index 6af5ae0..a6ba84f 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/autoapi/pygeohydro/nfhl/index.rst b/docs/source/autoapi/pygeohydro/nfhl/index.rst index 44d5500..e30f90d 100644 --- a/docs/source/autoapi/pygeohydro/nfhl/index.rst +++ b/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] diff --git a/docs/source/autoapi/pygeohydro/pygeohydro/index.rst b/docs/source/autoapi/pygeohydro/pygeohydro/index.rst index 4084271..b99b3f3 100644 --- a/docs/source/autoapi/pygeohydro/pygeohydro/index.rst +++ b/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 diff --git a/docs/source/autoapi/pygeohydro/stnfloodevents/index.rst b/docs/source/autoapi/pygeohydro/stnfloodevents/index.rst index d6b21fb..d7b4fb2 100644 --- a/docs/source/autoapi/pygeohydro/stnfloodevents/index.rst +++ b/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. diff --git a/docs/source/autoapi/pynhd/pynhd/index.rst b/docs/source/autoapi/pynhd/pynhd/index.rst index 0f520be..b39f0a8 100644 --- a/docs/source/autoapi/pynhd/pynhd/index.rst +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index c9523e0..638407e 100644 --- a/docs/source/conf.py +++ b/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,9 +208,15 @@ 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", @@ -216,27 +224,117 @@ "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) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 09fcae0..42ff488 100644 --- a/docs/source/getting_started.rst +++ b/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 + PyGeoHydro + Py3DEP + PyDaymet + PyGridMET + PyNLDAS2 + HydroSignatures + AsyncRetriever + PyGeoOGC + PyGeoUtils diff --git a/docs/source/index.rst b/docs/source/index.rst index eb9b5c6..717c233 100644 --- a/docs/source/index.rst +++ b/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:: diff --git a/docs/source/readmes.rst b/docs/source/readmes.rst deleted file mode 100644 index a391409..0000000 --- a/docs/source/readmes.rst +++ /dev/null @@ -1,112 +0,0 @@ -Software Stack -============== - -A detailed description of each component of the HyRiver 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 - -.. toctree:: - :maxdepth: 1 - :hidden: - - PyNHD - PyGeoHydro - Py3DEP - PyDaymet - PyGridMET - PyNLDAS2 - HydroSignatures - AsyncRetriever - PyGeoOGC - PyGeoUtils