From f76628da6c370bc0417658804ac85ff4e1eb7e68 Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 8 Apr 2026 12:35:19 +0100 Subject: [PATCH 1/9] Add sphinx basic settings for documentation and github actions workflow for deploying documentation --- .github/workflows/deploy-docs.yml | 68 +++++++++++++++++++ .gitignore | 2 + conda-env-linux-64.lock | 92 ++++++++++++++++++++++++++ docs/Makefile | 20 ++++++ docs/make.bat | 35 ++++++++++ docs/source/conf.py | 28 ++++++++ docs/source/development_guidelines.rst | 4 ++ docs/source/index.rst | 21 ++++++ docs/source/references.rst | 4 ++ docs/source/user_guide.rst | 4 ++ environment.yml | 14 ++++ 11 files changed, 292 insertions(+) create mode 100644 .github/workflows/deploy-docs.yml create mode 100644 conda-env-linux-64.lock create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/development_guidelines.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/references.rst create mode 100644 docs/source/user_guide.rst create mode 100644 environment.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..f59c3c6 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,68 @@ +# (C) Crown Copyright 2025, Met Office. +# The LICENSE file contains full licensing details. +name: Build and deploy the documentation + +on: + # Runs on pushes targeting the default branch. + push: + branches: ["profsea-climate"] + + # Allows you to run this workflow manually from the Actions tab. + workflow_dispatch: + +# Use a login shell so the Conda environment is activated. +defaults: + run: + shell: bash -leo pipefail {0} + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages. +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, +# skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs +# as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup GitHub Pages + uses: actions/configure-pages@v5 + + - uses: mamba-org/setup-micromamba@v2 + with: + environment-file: conda-env-linux-64.lock + environment-name: git-github-docs-env + cache-environment: true + cache-environment-key: env-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('conda-env-linux-64.lock') }} + + - name: Build with Sphinx + run: make --directory=docs html-all + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/build/html + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 8904e39..23fa56f 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,6 @@ *__pycache__* profsea.egg-info data/ +# Ignore the documentation build directory +docs/build *.DS_Store diff --git a/conda-env-linux-64.lock b/conda-env-linux-64.lock new file mode 100644 index 0000000..319868a --- /dev/null +++ b/conda-env-linux-64.lock @@ -0,0 +1,92 @@ +# This file may be used to create an environment using: +# $ conda create --name --file +# platform: linux-64 +@EXPLICIT +https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2 +https://conda.anaconda.org/conda-forge/noarch/ca-certificates-2026.1.4-hbd8a1cb_0.conda +https://conda.anaconda.org/conda-forge/linux-64/libgomp-15.2.0-he0feb66_16.conda +https://conda.anaconda.org/conda-forge/noarch/python_abi-3.14-8_cp314.conda +https://conda.anaconda.org/conda-forge/noarch/tzdata-2025c-hc9c84f9_1.conda +https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-2_gnu.tar.bz2 +https://conda.anaconda.org/conda-forge/linux-64/libgcc-15.2.0-he0feb66_16.conda +https://conda.anaconda.org/conda-forge/linux-64/bzip2-1.0.8-hda65f42_8.conda +https://conda.anaconda.org/conda-forge/linux-64/libexpat-2.7.3-hecca717_0.conda +https://conda.anaconda.org/conda-forge/linux-64/libffi-3.5.2-h9ec8514_0.conda +https://conda.anaconda.org/conda-forge/linux-64/liblzma-5.8.1-hb9d3cd8_2.conda +https://conda.anaconda.org/conda-forge/linux-64/libmpdec-4.0.0-hb9d3cd8_0.conda +https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-15.2.0-h934c35e_16.conda +https://conda.anaconda.org/conda-forge/linux-64/libuuid-2.41.3-h5347b49_0.conda +https://conda.anaconda.org/conda-forge/linux-64/libzlib-1.3.1-hb9d3cd8_2.conda +https://conda.anaconda.org/conda-forge/linux-64/ncurses-6.5-h2d0b736_3.conda +https://conda.anaconda.org/conda-forge/linux-64/openssl-3.6.0-h26f9b46_0.conda +https://conda.anaconda.org/conda-forge/linux-64/yaml-0.2.5-h280c20c_3.conda +https://conda.anaconda.org/conda-forge/linux-64/icu-78.2-h33c6efd_0.conda +https://conda.anaconda.org/conda-forge/linux-64/readline-8.3-h853b02a_0.conda +https://conda.anaconda.org/conda-forge/linux-64/tk-8.6.13-noxft_ha0e22de_103.conda +https://conda.anaconda.org/conda-forge/linux-64/zstd-1.5.7-hb78ec9c_6.conda +https://conda.anaconda.org/conda-forge/linux-64/ld_impl_linux-64-2.45-default_hbd61a6d_105.conda +https://conda.anaconda.org/conda-forge/linux-64/libsqlite-3.51.2-hf4e2dac_0.conda +https://conda.anaconda.org/conda-forge/linux-64/python-3.14.2-h32b2ec7_100_cp314.conda +https://conda.anaconda.org/conda-forge/noarch/alabaster-1.0.0-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/backports.zstd-1.3.0-py314h680f03e_0.conda +https://conda.anaconda.org/conda-forge/linux-64/brotli-python-1.2.0-py314h3de4e8d_1.conda +https://conda.anaconda.org/conda-forge/noarch/certifi-2026.1.4-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/cfgv-3.5.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/charset-normalizer-3.4.4-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/click-8.3.1-pyh8f84b5b_1.conda +https://conda.anaconda.org/conda-forge/noarch/colorama-0.4.6-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/distlib-0.4.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/docutils-0.21.2-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/filelock-3.20.3-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/hpack-4.1.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/hyperframe-6.1.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/idna-3.11-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/imagesize-1.4.1-pyhd8ed1ab_0.tar.bz2 +https://conda.anaconda.org/conda-forge/noarch/markupsafe-3.0.3-pyh7db6752_0.conda +https://conda.anaconda.org/conda-forge/noarch/packaging-25.0-pyh29332c3_1.conda +https://conda.anaconda.org/conda-forge/noarch/pip-25.3-pyh145f28c_0.conda +https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.5.1-pyhcf101f3_0.conda +https://conda.anaconda.org/conda-forge/noarch/pycparser-2.22-pyh29332c3_1.conda +https://conda.anaconda.org/conda-forge/noarch/pygments-2.19.2-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/pysocks-1.7.1-pyha55dd90_7.conda +https://conda.anaconda.org/conda-forge/noarch/pytz-2025.2-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/pyyaml-6.0.3-pyh7db6752_0.conda +https://conda.anaconda.org/conda-forge/noarch/roman-numerals-4.1.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/setuptools-80.9.0-pyhff2d567_0.conda +https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.0.1-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.8.1-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-1.0.1-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/typing_extensions-4.15.0-pyhcf101f3_0.conda +https://conda.anaconda.org/conda-forge/linux-64/websockets-16.0-py314h0f05182_1.conda +https://conda.anaconda.org/conda-forge/noarch/accessible-pygments-0.0.5-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/babel-2.17.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/linux-64/cffi-2.0.0-py314h4a8dc5f_1.conda +https://conda.anaconda.org/conda-forge/noarch/exceptiongroup-1.3.1-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/h11-0.16.0-pyhcf101f3_1.conda +https://conda.anaconda.org/conda-forge/noarch/h2-4.3.0-pyhcf101f3_0.conda +https://conda.anaconda.org/conda-forge/noarch/jinja2-3.1.6-pyhcf101f3_1.conda +https://conda.anaconda.org/conda-forge/noarch/nodeenv-1.10.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/roman-numerals-py-4.1.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.15.0-h396c80c_0.conda +https://conda.anaconda.org/conda-forge/noarch/virtualenv-20.36.1-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/anyio-4.12.1-pyhcf101f3_0.conda +https://conda.anaconda.org/conda-forge/noarch/beautifulsoup4-4.14.3-pyha770c72_0.conda +https://conda.anaconda.org/conda-forge/linux-64/ukkonen-1.0.1-py314h9891dd4_6.conda +https://conda.anaconda.org/conda-forge/noarch/urllib3-2.6.3-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/uvicorn-0.40.0-pyhc90fa1f_0.conda +https://conda.anaconda.org/conda-forge/noarch/identify-2.6.16-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/requests-2.32.5-pyhcf101f3_1.conda +https://conda.anaconda.org/conda-forge/noarch/starlette-0.51.0-pyhfdc7a7d_0.conda +https://conda.anaconda.org/conda-forge/linux-64/watchfiles-1.1.1-py314ha5689aa_0.conda +https://conda.anaconda.org/conda-forge/noarch/pre-commit-4.5.1-pyha770c72_0.conda +https://conda.anaconda.org/conda-forge/noarch/pydata-sphinx-theme-0.15.4-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/sphinx-autobuild-2025.8.25-pyhcf101f3_0.conda +https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.6.1-pyhd8ed1ab_2.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-2.0.0-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-2.0.0-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.1.0-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-mermaid-2.0.0-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-2.0.0-pyhd8ed1ab_1.conda +https://conda.anaconda.org/conda-forge/noarch/sphinx-8.2.3-pyhd8ed1ab_0.conda +https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-1.1.10-pyhd8ed1ab_1.conda diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..f5489a6 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'profsea-climate' +copyright = '2026, MetOffice' +author = 'isabellaascione' +release = '1.0.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/source/development_guidelines.rst b/docs/source/development_guidelines.rst new file mode 100644 index 0000000..abc683e --- /dev/null +++ b/docs/source/development_guidelines.rst @@ -0,0 +1,4 @@ +Development Guidelines +====================== + +This is the Development Guidelines page. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..efd4d01 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,21 @@ +.. profsea-climate documentation master file, created by + sphinx-quickstart on Wed Apr 8 11:10:23 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +profsea-climate documentation +============================= + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + user_guide + development_guidelines + references + diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 0000000..6392322 --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,4 @@ +References +========== + +This is the References page. diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst new file mode 100644 index 0000000..f267896 --- /dev/null +++ b/docs/source/user_guide.rst @@ -0,0 +1,4 @@ +User Guide +========== + +This is the User Guide page diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..5575a68 --- /dev/null +++ b/environment.yml @@ -0,0 +1,14 @@ +name: git-github-docs-env + +channels: + - https://metoffice.jfrog.io/metoffice/api/conda/conda-forge + - nodefaults + +dependencies: + - pre-commit + - sphinx-rtd-theme + - sphinx + - sphinx-autobuild + - sphinx-copybutton + - sphinx-design + - sphinxcontrib-mermaid From 1dbe12d135ebe2199b880bc43c5c7882e3597b0c Mon Sep 17 00:00:00 2001 From: James Frost Date: Wed, 8 Apr 2026 14:01:40 +0100 Subject: [PATCH 2/9] Update actions versions --- .github/workflows/deploy-docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index f59c3c6..2d5cb24 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -35,10 +35,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Setup GitHub Pages - uses: actions/configure-pages@v5 + uses: actions/configure-pages@v6 - uses: mamba-org/setup-micromamba@v2 with: @@ -51,7 +51,7 @@ jobs: run: make --directory=docs html-all - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v4 with: path: docs/build/html @@ -65,4 +65,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@v5 From 4c202884e1ab9ebc5381a2040c7b2fc268ee9e76 Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 8 Apr 2026 14:06:49 +0100 Subject: [PATCH 3/9] Update deploy-docs.yml remove html-all --- .github/workflows/deploy-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 2d5cb24..9e101ed 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -48,7 +48,7 @@ jobs: cache-environment-key: env-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('conda-env-linux-64.lock') }} - name: Build with Sphinx - run: make --directory=docs html-all + run: make --directory=docs html - name: Upload artifact uses: actions/upload-pages-artifact@v4 From 6710eb2b0f63d5b9fa82b84f1bab4cd7bbb4b463 Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 8 Apr 2026 14:14:31 +0100 Subject: [PATCH 4/9] update environment --- environment.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/environment.yml b/environment.yml index 5575a68..2f42468 100644 --- a/environment.yml +++ b/environment.yml @@ -1,4 +1,4 @@ -name: git-github-docs-env +name: profsea-climate-docs channels: - https://metoffice.jfrog.io/metoffice/api/conda/conda-forge @@ -8,7 +8,3 @@ dependencies: - pre-commit - sphinx-rtd-theme - sphinx - - sphinx-autobuild - - sphinx-copybutton - - sphinx-design - - sphinxcontrib-mermaid From 87db99f7c381f24d180def79eab70f1e916b71e0 Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 8 Apr 2026 14:15:07 +0100 Subject: [PATCH 5/9] update environment --- .github/workflows/deploy-docs.yml | 8 +-- conda-env-linux-64.lock | 92 ------------------------------- 2 files changed, 4 insertions(+), 96 deletions(-) delete mode 100644 conda-env-linux-64.lock diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 9e101ed..4e4635d 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -40,12 +40,12 @@ jobs: - name: Setup GitHub Pages uses: actions/configure-pages@v6 - - uses: mamba-org/setup-micromamba@v2 + - uses: mamba-org/setup-micromamba@v3 with: - environment-file: conda-env-linux-64.lock - environment-name: git-github-docs-env + environment-file: environment.yml + environment-name: profsea-climate-docs cache-environment: true - cache-environment-key: env-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('conda-env-linux-64.lock') }} + cache-environment-key: env-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('environment.yml') }} - name: Build with Sphinx run: make --directory=docs html diff --git a/conda-env-linux-64.lock b/conda-env-linux-64.lock deleted file mode 100644 index 319868a..0000000 --- a/conda-env-linux-64.lock +++ /dev/null @@ -1,92 +0,0 @@ -# This file may be used to create an environment using: -# $ conda create --name --file -# platform: linux-64 -@EXPLICIT -https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2 -https://conda.anaconda.org/conda-forge/noarch/ca-certificates-2026.1.4-hbd8a1cb_0.conda -https://conda.anaconda.org/conda-forge/linux-64/libgomp-15.2.0-he0feb66_16.conda -https://conda.anaconda.org/conda-forge/noarch/python_abi-3.14-8_cp314.conda -https://conda.anaconda.org/conda-forge/noarch/tzdata-2025c-hc9c84f9_1.conda -https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-2_gnu.tar.bz2 -https://conda.anaconda.org/conda-forge/linux-64/libgcc-15.2.0-he0feb66_16.conda -https://conda.anaconda.org/conda-forge/linux-64/bzip2-1.0.8-hda65f42_8.conda -https://conda.anaconda.org/conda-forge/linux-64/libexpat-2.7.3-hecca717_0.conda -https://conda.anaconda.org/conda-forge/linux-64/libffi-3.5.2-h9ec8514_0.conda -https://conda.anaconda.org/conda-forge/linux-64/liblzma-5.8.1-hb9d3cd8_2.conda -https://conda.anaconda.org/conda-forge/linux-64/libmpdec-4.0.0-hb9d3cd8_0.conda -https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-15.2.0-h934c35e_16.conda -https://conda.anaconda.org/conda-forge/linux-64/libuuid-2.41.3-h5347b49_0.conda -https://conda.anaconda.org/conda-forge/linux-64/libzlib-1.3.1-hb9d3cd8_2.conda -https://conda.anaconda.org/conda-forge/linux-64/ncurses-6.5-h2d0b736_3.conda -https://conda.anaconda.org/conda-forge/linux-64/openssl-3.6.0-h26f9b46_0.conda -https://conda.anaconda.org/conda-forge/linux-64/yaml-0.2.5-h280c20c_3.conda -https://conda.anaconda.org/conda-forge/linux-64/icu-78.2-h33c6efd_0.conda -https://conda.anaconda.org/conda-forge/linux-64/readline-8.3-h853b02a_0.conda -https://conda.anaconda.org/conda-forge/linux-64/tk-8.6.13-noxft_ha0e22de_103.conda -https://conda.anaconda.org/conda-forge/linux-64/zstd-1.5.7-hb78ec9c_6.conda -https://conda.anaconda.org/conda-forge/linux-64/ld_impl_linux-64-2.45-default_hbd61a6d_105.conda -https://conda.anaconda.org/conda-forge/linux-64/libsqlite-3.51.2-hf4e2dac_0.conda -https://conda.anaconda.org/conda-forge/linux-64/python-3.14.2-h32b2ec7_100_cp314.conda -https://conda.anaconda.org/conda-forge/noarch/alabaster-1.0.0-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/backports.zstd-1.3.0-py314h680f03e_0.conda -https://conda.anaconda.org/conda-forge/linux-64/brotli-python-1.2.0-py314h3de4e8d_1.conda -https://conda.anaconda.org/conda-forge/noarch/certifi-2026.1.4-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/cfgv-3.5.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/charset-normalizer-3.4.4-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/click-8.3.1-pyh8f84b5b_1.conda -https://conda.anaconda.org/conda-forge/noarch/colorama-0.4.6-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/distlib-0.4.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/docutils-0.21.2-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/filelock-3.20.3-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/hpack-4.1.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/hyperframe-6.1.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/idna-3.11-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/imagesize-1.4.1-pyhd8ed1ab_0.tar.bz2 -https://conda.anaconda.org/conda-forge/noarch/markupsafe-3.0.3-pyh7db6752_0.conda -https://conda.anaconda.org/conda-forge/noarch/packaging-25.0-pyh29332c3_1.conda -https://conda.anaconda.org/conda-forge/noarch/pip-25.3-pyh145f28c_0.conda -https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.5.1-pyhcf101f3_0.conda -https://conda.anaconda.org/conda-forge/noarch/pycparser-2.22-pyh29332c3_1.conda -https://conda.anaconda.org/conda-forge/noarch/pygments-2.19.2-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/pysocks-1.7.1-pyha55dd90_7.conda -https://conda.anaconda.org/conda-forge/noarch/pytz-2025.2-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/pyyaml-6.0.3-pyh7db6752_0.conda -https://conda.anaconda.org/conda-forge/noarch/roman-numerals-4.1.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/setuptools-80.9.0-pyhff2d567_0.conda -https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.0.1-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.8.1-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-1.0.1-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/typing_extensions-4.15.0-pyhcf101f3_0.conda -https://conda.anaconda.org/conda-forge/linux-64/websockets-16.0-py314h0f05182_1.conda -https://conda.anaconda.org/conda-forge/noarch/accessible-pygments-0.0.5-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/babel-2.17.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/linux-64/cffi-2.0.0-py314h4a8dc5f_1.conda -https://conda.anaconda.org/conda-forge/noarch/exceptiongroup-1.3.1-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/h11-0.16.0-pyhcf101f3_1.conda -https://conda.anaconda.org/conda-forge/noarch/h2-4.3.0-pyhcf101f3_0.conda -https://conda.anaconda.org/conda-forge/noarch/jinja2-3.1.6-pyhcf101f3_1.conda -https://conda.anaconda.org/conda-forge/noarch/nodeenv-1.10.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/roman-numerals-py-4.1.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.15.0-h396c80c_0.conda -https://conda.anaconda.org/conda-forge/noarch/virtualenv-20.36.1-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/anyio-4.12.1-pyhcf101f3_0.conda -https://conda.anaconda.org/conda-forge/noarch/beautifulsoup4-4.14.3-pyha770c72_0.conda -https://conda.anaconda.org/conda-forge/linux-64/ukkonen-1.0.1-py314h9891dd4_6.conda -https://conda.anaconda.org/conda-forge/noarch/urllib3-2.6.3-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/uvicorn-0.40.0-pyhc90fa1f_0.conda -https://conda.anaconda.org/conda-forge/noarch/identify-2.6.16-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/requests-2.32.5-pyhcf101f3_1.conda -https://conda.anaconda.org/conda-forge/noarch/starlette-0.51.0-pyhfdc7a7d_0.conda -https://conda.anaconda.org/conda-forge/linux-64/watchfiles-1.1.1-py314ha5689aa_0.conda -https://conda.anaconda.org/conda-forge/noarch/pre-commit-4.5.1-pyha770c72_0.conda -https://conda.anaconda.org/conda-forge/noarch/pydata-sphinx-theme-0.15.4-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/sphinx-autobuild-2025.8.25-pyhcf101f3_0.conda -https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.6.1-pyhd8ed1ab_2.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-2.0.0-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-2.0.0-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.1.0-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-mermaid-2.0.0-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-2.0.0-pyhd8ed1ab_1.conda -https://conda.anaconda.org/conda-forge/noarch/sphinx-8.2.3-pyhd8ed1ab_0.conda -https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-1.1.10-pyhd8ed1ab_1.conda From 330c5848336eca495160f22ce06ebfac2c23c1ae Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 8 Apr 2026 14:17:38 +0100 Subject: [PATCH 6/9] remove channels --- environment.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/environment.yml b/environment.yml index 2f42468..77783c9 100644 --- a/environment.yml +++ b/environment.yml @@ -1,8 +1,6 @@ name: profsea-climate-docs -channels: - - https://metoffice.jfrog.io/metoffice/api/conda/conda-forge - - nodefaults + dependencies: - pre-commit From 23065d807a85858397f923bfcce20e3b291b7782 Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 20 May 2026 12:10:47 +0100 Subject: [PATCH 7/9] example development and contribution guidelines --- docs/source/development_guidelines.rst | 59 ++++++++++++++++++ docs/source/documentation.rst | 82 ++++++++++++++++++++++++++ docs/source/index.rst | 1 + 3 files changed, 142 insertions(+) create mode 100644 docs/source/documentation.rst diff --git a/docs/source/development_guidelines.rst b/docs/source/development_guidelines.rst index abc683e..a60e751 100644 --- a/docs/source/development_guidelines.rst +++ b/docs/source/development_guidelines.rst @@ -1,4 +1,63 @@ +.. _development_guidelines: + Development Guidelines ====================== This is the Development Guidelines page. + +.. _open-an-issue: + +Open an Issue +------------- +Before forking the repository, open an issue in the main repository to describe the changes you plan to make. This helps maintainers track contributions and provide feedback early. + +.. _fork-the-repository: + +Fork the Repository +------------------- +First, create a fork of the repository in your GitHub account: + +1. Go to the repository page on GitHub. +2. Click the **Fork** button in the top-right corner. +3. Select your GitHub account as the destination for the fork. + +.. _clone-your-fork: + +Clone Your Fork +--------------- +Clone your forked repository and switch to the `profsea-climate` branch: + +.. code-block:: bash + + git clone git@github.com:/ProFSea-tool.git + cd ProFSea-tool + git checkout profsea-climate + +Replace ```` with your GitHub username. + +.. _commit-changes-to-your-fork: + +Commit Changes to Your Fork +--------------------------- +Once you are satisfied with your changes, commit and push them to your fork: + +.. code-block:: bash + + git add . + git commit -m "Adding feature: " + git push origin profsea-climate + +Replace ```` with a short summary of your updates. + +.. _create-a-pull-request: + +Create a Pull Request +--------------------- +To contribute your changes to the main repository: + +1. Go to your forked repository on GitHub. +2. Click the **Pull Request** button. +3. Select the ``profsea-climate`` branch of the main repository as the base branch. +4. Select the ``profsea-climate`` branch of your fork as the compare branch. +5. Add a title and description for your pull request. +6. Click **Create Pull Request**. diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst new file mode 100644 index 0000000..683e1e1 --- /dev/null +++ b/docs/source/documentation.rst @@ -0,0 +1,82 @@ +How to update the documentation +======================================== + +This is the page describing how to update the documentation. + +If you want to update the documentation, follow these steps to ensure that your changes are tested locally before contributing: + +1. Initial Steps +----------------------------------- +First of all you need to open an issue, fork and clone the repository. For detailed instructions, refer to the following sections in the :ref:`Development Guidelines ` page: + +- :ref:`Open an Issue ` +- :ref:`Fork the Repository ` +- :ref:`Clone Your Fork ` + +2. Set Up the Environment +------------------------- +Ensure you have the required dependencies installed to build the documentation. + +2.1 Create a Conda Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you are using Conda, create the environment from the ``environment.yml`` file: + +.. code-block:: bash + + conda env create -f environment.yml + conda activate profsea-climate-docs + +2.2 Install Dependencies with Pip (Optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you are not using Conda, install the dependencies with ``pip``: + +.. code-block:: bash + + pip install sphinx sphinx-rtd-theme + +3. Make Changes to the Documentation +------------------------------------- +Edit or add ``.rst`` files in the ``docs/source`` directory. For example: + +- Update ``index.rst`` to include new pages. +- Modify existing ``.rst`` files to update content. +- Add new ``.rst`` files for additional sections. + +4. Build the Documentation Locally +----------------------------------- +Before committing your changes, build the documentation locally to ensure there are no errors: + +.. code-block:: bash + + cd docs + make html + +This will generate the HTML files in the ``docs/build/html`` directory. Open the ``index.html`` file in your browser to preview the changes: + +.. code-block:: bash + + xdg-open build/html/index.html + +5. Test the Documentation +-------------------------- +- Verify that all links work correctly. +- Ensure the side menu and table of contents are updated. +- Check for any warnings or errors in the terminal output during the build process. + +6. Commit Changes and Create a Pull Request +--------------------------------------------- +Once you are satisfied with your changes, commit and push them to your fork. For detailed instructions, +refer to the following sections in the :ref:`Development Guidelines ` page: +- :ref:`Commit Changes to Your Fork ` +- :ref:`Create a Pull Request ` + +7. Verify Deployment +--------------------- +After your pull request is merged, the GitHub Actions workflow will automatically build and deploy the updated documentation. Verify that the changes are live on GitHub Pages: + +1. Go to the **Actions** tab in the main repository. +2. Check the logs for the ``deploy-docs.yml`` workflow to ensure it completed successfully. +3. Visit the GitHub Pages URL to confirm the updates. + +Notes +----- diff --git a/docs/source/index.rst b/docs/source/index.rst index efd4d01..d47e560 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,5 +17,6 @@ documentation for details. user_guide development_guidelines + documentation references From 70123174de8b52db9cbc7166130be28d4addf3c8 Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 27 May 2026 13:33:24 +0100 Subject: [PATCH 8/9] Adding docstring example and changing sphynx theme --- docs/source/conf.py | 48 +++++- docs/source/documentation.rst | 2 +- docs/source/index.rst | 26 +++ environment.yml | 2 +- profsea/spatial_projections.py | 290 +++++++++++++++++++++++---------- 5 files changed, 281 insertions(+), 87 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index f5489a6..547aa64 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,6 +3,11 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import sys + +sys.path.insert(0, os.path.abspath("../..")) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -14,7 +19,39 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", +] + +napoleon_google_docstring = False +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True + +autodoc_mock_imports = [ + "dask", + "matplotlib", + "netCDF4", + "numpy", + "pandas", + "profsea.config", + "profsea.directories", + "profsea.emulator", + "profsea.plotting_libraries", + "profsea.slr_pkg", + "profsea.utils", + "rich", + "scipy", + "xarray", +] templates_path = ['_templates'] exclude_patterns = [] @@ -24,5 +61,12 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'sphinx_rtd_theme' +html_theme = 'pydata_sphinx_theme' +html_theme_options = { + 'show_nav_level': 2, + 'secondary_sidebar_items': [], +} +html_sidebars = { + "**": ["search-field", "sidebar-nav-bs", "page-toc"], +} html_static_path = ['_static'] diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst index 683e1e1..69dcc11 100644 --- a/docs/source/documentation.rst +++ b/docs/source/documentation.rst @@ -32,7 +32,7 @@ If you are not using Conda, install the dependencies with ``pip``: .. code-block:: bash - pip install sphinx sphinx-rtd-theme + pip install sphinx pydata-sphinx-theme 3. Make Changes to the Documentation ------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index d47e560..3a86631 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,5 +18,31 @@ documentation for details. user_guide development_guidelines documentation + api_reference references +User Guide +---------- + +See :doc:`user_guide`. + +Development Guidelines +---------------------- + +See :doc:`development_guidelines`. + +Documentation Guide +------------------- + +See :doc:`documentation`. + +API Reference +------------- + +See :doc:`api_reference`. + +References +---------- + +See :doc:`references`. + diff --git a/environment.yml b/environment.yml index 77783c9..1d4b3f9 100644 --- a/environment.yml +++ b/environment.yml @@ -4,5 +4,5 @@ name: profsea-climate-docs dependencies: - pre-commit - - sphinx-rtd-theme + - pydata-sphinx-theme - sphinx diff --git a/profsea/spatial_projections.py b/profsea/spatial_projections.py index 0c45077..e9831d7 100644 --- a/profsea/spatial_projections.py +++ b/profsea/spatial_projections.py @@ -27,9 +27,18 @@ def calc_baseline_period(yrs: np.array) -> float: """ - Baseline years used for IPCC AR5 and Palmer et al 2020 -- 1986-2005 - :param yrs: years of the projections - :return: baseline years + Calculate the offset between projection start and AR5 baseline midpoint. + + Parameters + ---------- + yrs : numpy.ndarray + Projection years. + + Returns + ------- + float + Difference between the first projection year and the midpoint of the + 1986-2005 baseline period. """ byr1 = 1986. byr2 = 2005. @@ -41,11 +50,17 @@ def calc_baseline_period(yrs: np.array) -> float: def calc_future_sea_level(scenario: str) -> None: """ - Calculates future sea level at the given site and write to file. - :param df: Data frame of all metadata (tide gauge or site specific) for - each(all) location(s) - :param site_loc: name of the site location - :param scenario: emission scenario + Calculate and save future spatial sea-level projections for a scenario. + + Parameters + ---------- + scenario : str + Emissions scenario identifier. + + Returns + ------- + None + Outputs are written to configured NetCDF files. """ # Set the UKCP*18* random seed so results are reproducible np.random.seed(18) @@ -87,15 +102,23 @@ def calc_gia_contribution( yrs: np.array, nyrs: int, nsmps: int, scenario: str) -> None: """ - Calculate the glacial isostatic adjustment (GIA) contribution to the - regional component of sea level rise. - Option to use the generic global GIA estimates or use the GIA estimates - developed for UK as part of UKCP18. - :param yrs: years of the projections - :param nyrs: number of years in each projection time series - :param nsmps: determine the number of samples - :param coords: coordinates of location of interest - :return: GIA estimates converted to mm/yr + Calculate and save glacial isostatic adjustment (GIA) regional projections. + + Parameters + ---------- + yrs : numpy.ndarray + Projection years. + nyrs : int + Number of years in each projection time series. + nsmps : int + Number of samples to generate. + scenario : str + Emissions scenario identifier. + + Returns + ------- + None + GIA projections are written to a NetCDF output file. """ console.log('Calculating GIA contribution...') nGIA, GIA_vals = read_gia_estimates() @@ -142,11 +165,19 @@ def calc_gia_contribution( def calc_expansion_contribution( scenario: str, nsmps: int) -> da.array: """ - Calculate the thermal expansion contribution to the regional component of - sea level rise. - :param scenario: emission scenario - :param nsmps: determine the number of samples - :return: expansion estimates converted to mm/yr + Sample thermal expansion coefficients for regional projections. + + Parameters + ---------- + scenario : str + Emissions scenario identifier. + nsmps : int + Number of samples to draw. + + Returns + ------- + dask.array.Array + Sampled expansion coefficients on the target grid. """ # Select slope coefficients based on the MIP if settings["emulator_settings"]["emulator_mode"]: @@ -166,9 +197,21 @@ def calc_expansion_contribution( def calc_landwater_contribution(data: dict, lats: int, lons: int) -> da.array: """ - Calculate the regional landwater contribution to sea level rise. - :param interpolator: dictionary of interpolator objects - :return: numpy array of landwater values + Interpolate and re-grid landwater contribution fields. + + Parameters + ---------- + data : dict + Landwater input data used for interpolation. + lats : int + Number of latitude points in the target grid. + lons : int + Number of longitude points in the target grid. + + Returns + ------- + dask.array.Array + Landwater contribution values on the target grid. """ landwater_vals = interpolate(data, lats, lons) landwater_vals = da.roll(landwater_vals, 180, axis=1) @@ -177,6 +220,25 @@ def calc_landwater_contribution(data: dict, lats: int, lons: int) -> da.array: def calc_fingerprint_contributions( FPlist: list, comp: str, lats: int, lons: int) -> da.array: + """ + Interpolate and stack fingerprints for a selected component. + + Parameters + ---------- + FPlist : list + List of fingerprint dictionaries. + comp : str + Component key to extract from each fingerprint dictionary. + lats : int + Number of latitude points in the target grid. + lons : int + Number of longitude points in the target grid. + + Returns + ------- + dask.array.Array + Stacked fingerprint values for the selected component. + """ # Initiate an empty list for fingerprint values fp_vals = [] for FP_dict in FPlist: @@ -190,12 +252,19 @@ def calc_fingerprint_contributions( def calc_greenland_fingerprint_ar6(lats: int, lons: int) -> da.array: - """Load and prepare the GIS fingerprint. - - This fingerprint was/is used by FACTS for AR6 projections, and was - originally calculated by Mitrovica et al., (2011). - - :return dask array containing GIS fingerprint + """Load and prepare the AR6 Greenland fingerprint. + + Parameters + ---------- + lats : int + Number of latitude points in the target grid. + lons : int + Number of longitude points in the target grid. + + Returns + ------- + dask.array.Array + Greenland fingerprint on the target grid. """ # Load in the fingerprint fp_path = Path(settings["fingerprints"]) / "greenland_ar6.nc" @@ -216,11 +285,23 @@ def calc_greenland_fingerprint_ar6(lats: int, lons: int) -> da.array: def save_projections( montecarlo_R: da.array, component: str, scenario: str, percentile: da.array) -> None: """ - Save the regional sea level projections to a file. - :param montecarlo_R: regional sea level projections - :param component: sea level component - :param scenario: emission scenario - :param percentile: percentiles used for spatial projections + Save regional sea-level projections for one component to NetCDF. + + Parameters + ---------- + montecarlo_R : dask.array.Array + Regional sea-level projections. + component : str + Sea-level component name. + scenario : str + Emissions scenario identifier. + percentile : dask.array.Array or numpy.ndarray + Percentiles represented in the first dimension. + + Returns + ------- + None + Data are written to a component-specific NetCDF file. """ sealev_ddir = os.path.join(settings["baseoutdir"],settings["experiment_name"], settings['emulator_settings']['spatial_output_dir']) @@ -247,18 +328,25 @@ def calculate_sl_components( mcdir: str, components: list, scenario: str, yrs: np.array, array_dims: list) -> None: """ - Calculates global and regional component part contributions to sea level - change. - :param mcdir: location of Monte Carlo time series for new projections - :param components: sea level components - :param scenario: emission scenario - :param yrs: years of the projections - :param array_dims: Array of nesm, nsmps and nyrs - nesm --> Number of ensemble members in time series - nsmps --> Determine the number of samples you wish to make - nyrs --> Number of years in each projection time series - :return: montecarlo_G (global contribution to sea level rise) and - montecarlo_R (regional contribution to sea level change) + Calculate regional contributions for all selected sea-level components. + + Parameters + ---------- + mcdir : str + Directory containing Monte Carlo time series inputs. + components : list + Sea-level components to project. + scenario : str + Emissions scenario identifier. + yrs : numpy.ndarray + Projection years. + array_dims : list + Dimensions in the order [nesm, nsmps, nyrs, lats, lons]. + + Returns + ------- + None + Component-specific NetCDF outputs are written to disk. """ # Numbers of ensemble members, samples, years nesm, nsmps, nyrs, lats, lons = array_dims @@ -310,12 +398,19 @@ def calculate_sl_components( def get_projection_info(indir: str, scenario: str) -> tuple: """ - Read in the dimensions of the Monte-Carlo data. These files are all - relative to midnight on 1st January 2007 - :param indir: directory of Monte Carlo time series for new projections - :param scenario: emission scenarios to be considered - :return: Number of ensemble members in time series, number of years in - each projection time series and the years of the projections + Read dimensions and years from a Monte Carlo NetCDF sample file. + + Parameters + ---------- + indir : str + Input directory containing Monte Carlo files. + scenario : str + Emissions scenario identifier. + + Returns + ------- + tuple + Tuple of (number of ensemble members, number of years, years array). """ sample_file = f'{scenario}_exp.nc' f = Dataset(f'{indir}{sample_file}', 'r') @@ -332,13 +427,17 @@ def get_projection_info(indir: str, scenario: str) -> tuple: def load_CMIP5_slope_coeffs(scenario: str) -> np.ndarray: """ - Loads in the CMIP slope coefficients based on linear regression of - 'zos+zostoga' against 'zostoga' for the period 2005 to 2100. - Some models are missing regression slopes for RCP2.6. If so, use RCP4.5 - values instead. - :param site_loc: name of the site location - :param scenario: emissions scenario - :return: 1D array of regression coefficients + Load CMIP5 slope coefficients for a selected scenario. + + Parameters + ---------- + scenario : str + Emissions scenario identifier. + + Returns + ------- + numpy.ndarray + Regression slope coefficients on the spatial grid. """ # Read in the sea level regressions in_zosddir = read_dir()[2] @@ -354,10 +453,17 @@ def load_CMIP5_slope_coeffs(scenario: str) -> np.ndarray: def load_CMIP6_slopes(scenario: str) -> np.ndarray: """ - Load in the CMIP6 slope coefficients. - :param site_loc: name of the site location - :param scenario: emissions scenario - :return: 1D array of regression coefficients + Load CMIP6 slope coefficients for a selected scenario. + + Parameters + ---------- + scenario : str + Emissions scenario identifier. + + Returns + ------- + dask.array.Array + Stacked slope coefficients across available models. """ # Read in the sea level regressions cmip6_dir = settings["cmipinfo"]["sealevelbasedir"] @@ -377,11 +483,12 @@ def load_one_slope(f): def read_gia_estimates() -> tuple: """ - Read in pre-processed interpolator objects of GIA estimates (Lambeck, - ICE5G) - :param: none - :return: length of GIA_vals and numpy array of pre-processed interpolator - objects of GIA estimates + Read and prepare pre-processed GIA estimate fields. + + Returns + ------- + tuple + Tuple of (number of GIA fields, array of GIA values). """ gia_file = settings["giaestimates"]["global"] with open(gia_file, "rb") as ifp: @@ -405,11 +512,17 @@ def read_gia_estimates() -> tuple: def load_fingerprints(components: list) -> tuple: """ - Create 2D Interpolator objects for the Slangen, Spada and Klemann - fingerprints - :param components: list of sea level components - :return nFPs: length of FPlist and interpolator objects of all sea level - components + Load component fingerprints from multiple fingerprint datasets. + + Parameters + ---------- + components : list + Sea-level components to load. + + Returns + ------- + tuple + Tuple of (number of fingerprint sets, list of fingerprint dictionaries). """ # Create empty dictionaries for the Slangen, Spada and Klemann fingerprints # interpolator objects. @@ -445,10 +558,19 @@ def load_fingerprints(components: list) -> tuple: def calculate_global_components(scenario: str, palmer_method: bool) -> None: """ - Calculate the global contributions for each of the sea-level components - using the GMSLR module. - :param scenario: string representing the scenario being simulated - :param palmer_method: boolean to determine whether to use the palmer_method + Calculate global component projections using the GMSLR emulator. + + Parameters + ---------- + scenario : str + Scenario being simulated. + palmer_method : bool + Whether to apply the Palmer method beyond 2100. + + Returns + ------- + None + Global component outputs are saved to disk. """ # Check inputs are correctly set up if not (os.path.exists(settings["scm_data"]["temperature"]) and @@ -505,10 +627,12 @@ def calculate_global_components(scenario: str, palmer_method: bool) -> None: def main(): """ - Reads in and calculates global and local (regional) sea level change - (sum total), based on the different contributing factors e.g. thermal - expansion, GIA and mass balance. Writes out the selected emissions scenario - estimates of the various components and their sums. + Run end-to-end global and regional sea-level projection workflows. + + Returns + ------- + None + Projection files are generated in configured output directories. """ console.log(f'\nProjecting out to: {settings["projection_end_year"]}\n') From 037054c65b8b0b2e190de7d3b9b1852ac0cc7eba Mon Sep 17 00:00:00 2001 From: isabellaascione Date: Wed, 27 May 2026 13:39:54 +0100 Subject: [PATCH 9/9] add api_reference --- docs/source/api_reference.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/source/api_reference.rst diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst new file mode 100644 index 0000000..ee1d0a7 --- /dev/null +++ b/docs/source/api_reference.rst @@ -0,0 +1,25 @@ +API Reference +============= + +This page exposes selected Python API docs generated from in-code docstrings. + +Spatial Projections Module +-------------------------- + +.. automodule:: profsea.spatial_projections + :no-members: + +calc_future_sea_level +~~~~~~~~~~~~~~~~~~~~~ + +.. autofunction:: profsea.spatial_projections.calc_future_sea_level + +calculate_global_components +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. autofunction:: profsea.spatial_projections.calculate_global_components + +calculate_sl_components +~~~~~~~~~~~~~~~~~~~~~~~ + +.. autofunction:: profsea.spatial_projections.calculate_sl_components