diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..df68a07 --- /dev/null +++ b/.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/setup-pixi@v0.9.4 + 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" diff --git a/livvext/__init__.py b/livvext/__init__.py index a20bfc8..f7686e3 100644 --- a/livvext/__init__.py +++ b/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__) diff --git a/livvext/common.py b/livvext/common.py index 80d427f..28e9e9b 100644 --- a/livvext/common.py +++ b/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 diff --git a/livvext/utils.py b/livvext/utils.py index cea6f59..88a69cc 100644 --- a/livvext/utils.py +++ b/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: diff --git a/pyproject.toml b/pyproject.toml index f87fa22..8b64a18 100644 --- a/pyproject.toml +++ b/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"]