Update dependencies, add initial documentation

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: Docs
+on:
+  push:
+    branches: [ "main" ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.14
+
+    - name: Set up Pixi ${{ matrix.python-version }}
+      uses: prefix-dev/[email protected]
+      with:
+        pixi-version: v0.62.2
+        # Project environment caching uses pixi.lock as the cache key input.
+        # If you don't commit a lockfile, disable caching to avoid ENOENT.
+        # cache: ${{ hashFiles('pixi.lock') != '' }}
+        environments: docs
+
+    - name: Generate API documentation with pydoctor
+      run: |
+
+        # Run pydoctor build
+        pixi run -e docs pydoctor \
+            --project-url=https://github.com/$GITHUB_REPOSITORY \
+            --html-viewsource-base=https://github.com/$GITHUB_REPOSITORY/tree/$GITHUB_SHA \
+            --config pyproject.toml
+
+    - name: Push API documentation to Github Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs
+        commit_message: "Generate API documentation"

livvext/__init__.py

@@ -31,5 +31,5 @@
 Storage for global variables.  These are set upon startup in the options module
 """
 
-__version_info__ = (1, 0, 1)
+__version_info__ = (1, 0, 2)
 __version__ = ".".join(str(vi) for vi in __version_info__)

livvext/common.py

@@ -516,7 +516,7 @@ def area_avg(
     data : array_like
         Array of data to be averaged
     config : dict
-        LIVVkit configuration dictionary, at least contains the `maskv` variable
+        LIVVkit configuration dictionary, at least contains the variable `maskv`
         if `mask_var` is not set
     area_file : Path
         Path to a netCDF file containing the grid cell area which matches `data`
@@ -746,9 +746,6 @@ def compute_clevs(
     ----------
     data : dictionary
         Masked array of data for which to compute contour levels
-    data_1, data_2 : array_like, optional
-        Masked arrays of data, to use in computation of contour levels if needed
-        (default: None)
     bnds : tuple, optional
         Upper / lower percentiles to use for bounds (default: (5%, 95%))
     even : bool, optional

livvext/utils.py

@@ -113,16 +113,16 @@ def _bib2html_bibdata(bib, style=None, backend=None):
 
 
 def eval_expr(expr):
-    """
+    r"""
     Evaluate a mathematical expression stored as a string in a JSON file.
 
     Parameters
     ----------
     expr : str
         Mathematical expression, stored as a single string: e.g.
-        "1 + 1 * 3", "24 * 3600 * 365", etc.
+        "1 + 1 \* 3", "24 \* 3600 \* 365", etc.
         Will be checked to contain _only_ numbers and mathematical symbols:
-        [0-9], +, -, *, /, ^, (, and )
+        [0-9], +, -, \*, /, ^, (, and )
     Returns
     -------
     result : float
@@ -212,6 +212,26 @@ def extract_vars(expr):
 
 
 def apply_operator(operands, operator, name=False):
+    r"""
+    Recursively apply mathematical operator(s).
+
+    Parameters
+    ----------
+    operands : list
+        List of operands, either two field names, or a field name and another list
+        of field names (e.g. [U, V], or [T, [U, V]], or [T, [U, [V, X]]])
+    operator : str
+        Operator to apply recursively to the pairs of operands (one of +, -, \*, /, or ^)
+    name : bool
+        If true, return a string of the applied operation, if false, return the value.
+
+    Returns
+    -------
+    output : (type(operands), str)
+        Returns the result of the mathematical expression, with the same type as
+        `operands[0]` or a string representation of the expression
+
+    """
     ops = {
         "+": op.add,
         "-": op.sub,
@@ -245,19 +265,31 @@ def extract_name(expr):
         two elements are operands, either numeric values, fields within `dset`,
         or an expression of this kind.
         (e.g. ["^", ["+", ["*", "U", "U"], ["*", "V", "V"]], "0.5"] for the wind velocity)
-    dset : xarray.Dataset
-        Dataset which contains the fields described in `expr`
 
     Returns
     -------
-    output : xarray.DataArray
-        Evaluated expression
+    output : str
+        Human redable text of evaluated expression
 
     """
     return extract_ds(expr, {}, name=True)
 
 
 def will_it_float(test_str: str) -> bool:
+    """
+    Test a string to determine if it will convert to a float.
+
+    Parameters
+    ----------
+    test_str : str
+        String to be tested
+
+    Returns
+    -------
+    _will : float, bool
+        If the string converts to a float, return the float, if not return False
+
+    """
     try:
         _will = float(test_str)
     except ValueError:

pyproject.toml

@@ -46,17 +46,17 @@ dependencies = [
     "numpy>=2.2.6",
     "scipy>=1.17.0",
     "xarray>=2025.6.1",
-    "dask>=2026.1.2",
+    "dask>=2025.9.1",
     "seaborn>=0.13.2",
     "cftime>=1.6.5",
-    "nc-time-axis>=1.4.1",
+    "nc-time-axis",
     "scikit-learn>=1.7.2",
     "ruamel.yaml>=0.19.1",
     "jinja2>=3.1.6",
-    "matplotlib>=3.10.8",
-    "netcdf4>=1.7.4",
+    "matplotlib>=3.10.6",
+    "netcdf4>=1.7.2",
     "pandas>=2.2.3",
-    "cartopy>=0.25.0",
+    "cartopy>=0.17.0",
     "pybtex>=0.25.1",
     "f90nml>=1.5",
     "loguru>=0.7.3",
@@ -134,11 +134,26 @@ python = "3.14.*"
 [tool.pixi.environments]
 default = { solve-group = "default" }
 dev = ["dev"]
+docs = ["docs"]
 py311dev = ["py311dev", "dev"]
 py312dev = ["py312dev", "dev"]
 py313dev = ["py313dev", "dev"]
 py314dev = ["py314dev", "dev"]
-buildenv = ["py314dev", "buildenv"]
+buildenv = ["buildenv"]
 
 [dependency-groups]
 buildenv = ["build>=1.4.0,<2"]
+docs = ["pydoctor", "docutils"]
+
+[tool.pydoctor]
+project-name = "LIVVext"
+make-html = true
+html-output = "./docs"
+docformat = "numpy"
+intersphinx = [
+    "https://docs.python.org/3/objects.inv",
+     "http://xarray.pydata.org/en/latest/objects.inv"
+]
+theme = "readthedocs"
+privacy = ["PRIVATE:**.__*__", "PUBLIC:**.__init__", "PRIVATE:**.ipynb_checkpoints"]
+add-package = ["./livvext", "./livvext/smb", "./livvext/energy"]