docs: Various improvements

oceanmodeling · Jun 26, 2024 · 1497b04 · 1497b04
1 parent f28baef
commit 1497b04
Show file tree

Hide file tree

Showing 8 changed files with 48 additions and 13 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -73,10 +73,17 @@ def repository_root(path: PathLike = None) -> Path:
     "sphinx.ext.autosummary",
     # The Napoleon extension allows for nicer argument formatting.
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
     "sphinxext.opengraph",
     "m2r2",
 ]
 
+# sphinx_autodoc_typehints settings
+always_use_bars_union = True
+typehints_use_rtype = False
+typehints_use_signature = False
+typehints_use_signature_return = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

diff --git a/docs/source/coops.rst b/docs/source/coops.rst
@@ -59,5 +59,5 @@ The ``COOPS_Query`` class lets you send an individual query to the CO-OPS API by
 New API
 -------
 
-.. autofunction:: searvey.coops.get_coops_stations
-.. autofunction:: searvey.coops.fetch_coops_station
+.. autofunction:: searvey.get_coops_stations
+.. autofunction:: searvey.fetch_coops_station
diff --git a/docs/source/ioc.rst b/docs/source/ioc.rst
@@ -6,15 +6,15 @@ website is focused on operational monitoring of sea level measuring stations acr
 `Intergovernmental Oceanographic Commission (IOC) <https://ioc.unesco.org>`_ aggregating data from more than 170 providers.
 
 
-A list of IOC stations is provided with the ``get_ioc_stations()`` function with various subsetting options.
+A DataFrame with the IOC station metadata can be retrieved with ``get_ioc_stations()``
+while the station data can be fetched with ``fetch_ioc_station()``:
 
-.. autofunction:: searvey.ioc.get_ioc_stations
+.. autofunction:: searvey.get_ioc_stations
 
-The station data can be retrieved with
 
-.. autofunction:: searvey.ioc.get_ioc_data
+.. autofunction:: searvey.fetch_ioc_station
 
-New API
--------
+Deprecated API
+``````````````
 
-.. autofunction:: searvey.ioc.fetch_ioc_station
+.. autofunction:: searvey.get_ioc_data
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -70,6 +70,7 @@ setuptools = "*"
 sphinx = "*"
 sphinxext-opengraph = "*"
 toml = "*"
+sphinx-autodoc-typehints = "*"
 
 [tool.poetry.group.jupyter.dependencies]
 ipykernel = "*"

diff --git a/requirements/requirements-dev.txt b/requirements/requirements-dev.txt
@@ -108,6 +108,7 @@ six==1.16.0 ; python_version >= "3.9" and python_version < "4.0"
 sniffio==1.3.1 ; python_version >= "3.9" and python_version < "4.0"
 snowballstemmer==2.2.0 ; python_version >= "3.9" and python_version < "4.0"
 soupsieve==2.5 ; python_version >= "3.9" and python_version < "4.0"
+sphinx-autodoc-typehints==2.1.1 ; python_version >= "3.9" and python_version < "4.0"
 sphinx-basic-ng==1.0.0b2 ; python_version >= "3.9" and python_version < "4.0"
 sphinx==7.3.7 ; python_version >= "3.9" and python_version < "4.0"
 sphinxcontrib-applehelp==1.0.8 ; python_version >= "3.9" and python_version < "4.0"

diff --git a/searvey/_ioc_api.py b/searvey/_ioc_api.py
@@ -234,6 +234,11 @@ def fetch_ioc_station(
     Make a query to the IOC API for tide gauge data for ``station_id``
     and return the results as a ``pandas.Dataframe``.
 
+    .. code-block:: python
+
+        fetch_ioc_station("acap2")
+        fetch_ioc_station("acap2", start_date="2023-01-01", end_date="2023-01-02")
+
     ``start_date`` and ``end_date`` can be of any type that is valid for ``pandas.to_datetime()``.
     If ``start_date`` or ``end_date`` are timezone-aware timestamps they are coersed to UTC.
     The returned data are always in UTC.
@@ -259,10 +264,11 @@ def fetch_ioc_station(
     :param start_date: The starting date of the query. Defaults to 7 days ago.
     :param end_date: The finishing date of the query. Defaults to "now".
     :param rate_limit: The rate limit for making requests to the IOC servers. Defaults to 5 requests/second.
-    :param http_client: The ``httpx.Client``.
+    :param http_client: The ``httpx.Client``. Can be used to setup e.g. an HTTP proxy.
     :param multiprocessing_executor: An instance of a class implementing the ``concurrent.futures.Executor`` API.
     :param multithreading_executor: An instance of a class implementing the ``concurrent.futures.Executor`` API.
     :param progress_bar: If ``True`` then a progress bar is displayed for monitoring the progress of the outgoing requests.
+    :return: ``pandas.DataFrame`` with the station data.
     """
     logger.info("IOC-%s: Starting scraping: %s - %s", station_id, start_date, end_date)
     now = pd.Timestamp.now("utc")

diff --git a/searvey/ioc.py b/searvey/ioc.py
@@ -202,12 +202,12 @@ def get_ioc_stations(
 
     Note: The longitudes of the IOC stations are in the [-180, 180] range.
 
-    :param region: ``Polygon`` or ``MultiPolygon`` denoting region of interest
+    :param region: ``Polygon`` or ``MultiPolygon`` denoting region of interest.
     :param lon_min: The minimum Longitude of the Bounding Box.
     :param lon_max: The maximum Longitude of the Bounding Box.
     :param lat_min: The minimum Latitude of the Bounding Box.
     :param lat_max: The maximum Latitude of the Bounding Box.
-    :return: ``pandas.DataFrame`` with the station metadata
+    :return: ``pandas.DataFrame`` with the station metadata.
     """
     region = get_region(
         region=region,
@@ -341,6 +341,7 @@ def get_ioc_data(
     :param truncate_seconds: If ``True`` then timestamps are truncated to minutes (seconds are dropped)
     :param rate_limit: The default rate limit is 5 requests/second.
     :param disable_progress_bar: If ``True`` then the progress bar is not displayed.
+    :returns: An ``xr.Dataset`` with the station data.
 
     """
     if period > IOC_MAX_DAYS_PER_REQUEST: