Add Sphinx documentation

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs Build Check
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install sphinx sphinx-rtd-theme myst-parser
+
+    - name: Build docs
+      run: |
+        cd docs
+        make html

.gitignore

@@ -1,4 +1,5 @@
 build/
+docs/_build/
 .venv/
 .vscode/
 *.egg-info/

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: requirements.txt
+    - method: pip
+      path: .

docs/Makefile

@@ -0,0 +1,21 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -j auto
+SPHINXBUILD   ?= sphinx-build
+SPHINXPROJ    = RivRetrieve-Python
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for SPHINXOPTS.
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,24 @@
+API Reference
+=============
+
+.. automodule:: rivretrieve
+   :members:
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Fetchers:
+
+   fetchers/australia
+   fetchers/brazil
+   fetchers/canada
+   fetchers/chile
+   fetchers/czech
+   fetchers/france
+   fetchers/japan
+   fetchers/poland
+   fetchers/portugal
+   fetchers/slovenia
+   fetchers/southafrica
+   fetchers/uk_ea
+   fetchers/uk_nrfa
+   fetchers/usa

docs/conf.py

@@ -0,0 +1,71 @@
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+project = "RivRetrieve-Python"
+copyright = "2025, Frederik Kratzert"
+author = "Frederik Kratzert"
+release = "0.1.0"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+
+from rivretrieve import constants
+
+
+def autodoc_process_docstring(app, what, name, obj, options, lines):
+    if not lines:
+        return
+
+    new_lines = []
+
+    for line in lines:
+        matches = re.findall(r"constants\.([A-Z_]+)", line)
+
+        for match in matches:
+            if hasattr(constants, match):
+                const_val = getattr(constants, match)
+
+                line = line.replace(f"constants.{match}", f"'{const_val}'")
+
+        new_lines.append(line)
+
+    lines[:] = new_lines
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    # Skip class attributes that are all uppercase (likely constants)
+    if what == "class" and name.isupper() and not callable(obj):
+        return True
+    return skip
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", autodoc_process_docstring)
+    app.connect("autodoc-skip-member", autodoc_skip_member)

docs/fetchers/australia.rst

@@ -0,0 +1,5 @@
+Australia Fetcher
+=================
+
+.. automodule:: rivretrieve.australia
+   :members:

docs/fetchers/brazil.rst

@@ -0,0 +1,5 @@
+Brazil Fetcher
+==============
+
+.. automodule:: rivretrieve.brazil
+   :members:

docs/fetchers/canada.rst

@@ -0,0 +1,5 @@
+Canada Fetcher
+==============
+
+.. automodule:: rivretrieve.canada
+   :members:

docs/fetchers/chile.rst

@@ -0,0 +1,5 @@
+Chile Fetcher
+=============
+
+.. automodule:: rivretrieve.chile
+   :members:

docs/fetchers/czech.rst

@@ -0,0 +1,5 @@
+Czech Fetcher
+=============
+
+.. automodule:: rivretrieve.czech
+   :members:

docs/fetchers/france.rst

@@ -0,0 +1,5 @@
+France Fetcher
+==============
+
+.. automodule:: rivretrieve.france
+   :members:

docs/fetchers/japan.rst

@@ -0,0 +1,5 @@
+Japan Fetcher
+=============
+
+.. automodule:: rivretrieve.japan
+   :members:

docs/fetchers/poland.rst

@@ -0,0 +1,5 @@
+Poland Fetcher
+==============
+
+.. automodule:: rivretrieve.poland
+   :members:

docs/fetchers/portugal.rst

@@ -0,0 +1,5 @@
+Portugal Fetcher
+================
+
+.. automodule:: rivretrieve.portugal
+   :members:

docs/fetchers/slovenia.rst

@@ -0,0 +1,5 @@
+Slovenia Fetcher
+================
+
+.. automodule:: rivretrieve.slovenia
+   :members:

docs/fetchers/southafrica.rst

@@ -0,0 +1,5 @@
+South Africa Fetcher
+====================
+
+.. automodule:: rivretrieve.southafrica
+   :members:

docs/fetchers/uk_ea.rst

@@ -0,0 +1,5 @@
+UK EA Fetcher
+=============
+
+.. automodule:: rivretrieve.uk_ea
+   :members:

docs/fetchers/uk_nrfa.rst

@@ -0,0 +1,5 @@
+UK NRFA Fetcher
+===============
+
+.. automodule:: rivretrieve.uk_nrfa
+   :members:

docs/fetchers/usa.rst

@@ -0,0 +1,5 @@
+USA Fetcher
+===========
+
+.. automodule:: rivretrieve.usa
+   :members:

docs/index.rst

@@ -0,0 +1,16 @@
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pyproject.toml

@@ -18,4 +18,5 @@ select = [
 
 [tool.ruff.lint.per-file-ignores]
 "rivretrieve/__init__.py" = ["F401"]
-"rivretrieve/chile.py" = ["E501"]  # The url is too long but can't be splitted.
+"rivretrieve/chile.py" = ["E501"]  # The url is too long but can't be splitted.
+"docs/conf.py" = ["E402"]  # rivretrieve can't be imported before path is added.

requirements.txt

@@ -11,4 +11,7 @@ parameterized
 python-dotenv
 ruff
 tqdm
-zarr>=3.0.7
+zarr>=3.0.7
+sphinx>=8.0.0
+sphinx-rtd-theme>=3.0.0
+myst-parser>=4.0.0

rivretrieve/australia.py

@@ -14,13 +14,27 @@
 
 
 class AustraliaFetcher(base.RiverDataFetcher):
-    """Fetches river gauge data from Australia's BoM."""
+    """Fetches river gauge data from Australia's Bureau of Meteorology (BoM).
+
+    Data Source: Bureau of Meteorology Water Data Online (http://www.bom.gov.au/waterdata/)
+
+    Supported Variables:
+        - ``constants.DISCHARGE_DAILY_MEAN`` (m³/s)
+        - ``constants.STAGE_DAILY_MEAN`` (m)
+    """
 
     BOM_URL = "http://www.bom.gov.au/waterdata/services"
 
     @staticmethod
     def get_cached_metadata() -> pd.DataFrame:
-        """Retrieves a DataFrame of available Australian gauge IDs and metadata."""
+        """Retrieves a DataFrame of available Australian gauge IDs and metadata.
+
+        This method loads the metadata from a cached CSV file located in
+        the ``rivretrieve/cached_site_data/`` directory.
+
+        Returns:
+            pd.DataFrame: A DataFrame indexed by gauge_id, containing site metadata.
+        """
         return utils.load_cached_metadata_csv("australia")
 
     @staticmethod
@@ -160,7 +174,31 @@ def get_data(
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
     ) -> pd.DataFrame:
-        """Fetches and parses Australian river gauge data."""
+        """Fetches and parses time series data for a specific gauge and variable.
+
+        This method retrieves the requested data from the provider's API or data source,
+        parses it, and returns it in a standardized pandas DataFrame format.
+
+        Args:
+            gauge_id: The site-specific identifier for the gauge.
+            variable: The variable to fetch. Must be one of the strings listed
+                in the fetcher's ``get_available_variables()`` output.
+                These are typically defined in ``rivretrieve.constants``.
+            start_date: Optional start date for the data retrieval in 'YYYY-MM-DD' format.
+                If None, data is fetched from the earliest available date.
+            end_date: Optional end date for the data retrieval in 'YYYY-MM-DD' format.
+                If None, data is fetched up to the latest available date.
+
+        Returns:
+            pd.DataFrame: A pandas DataFrame indexed by datetime objects (``constants.TIME_INDEX``)
+            with a single column named after the requested ``variable``. The DataFrame
+            will be empty if no data is found for the given parameters.
+
+        Raises:
+            ValueError: If the requested ``variable`` is not supported by this fetcher.
+            requests.exceptions.RequestException: If a network error occurs during data download.
+            Exception: For other unexpected errors during data fetching or parsing.
+        """
         start_date = utils.format_start_date(start_date)
         end_date = utils.format_end_date(end_date)
         if variable not in self.get_available_variables():