Building documentation

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: "2"
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true

README.md

@@ -1,10 +1,11 @@
 # cloudcasting
 
 [![Actions Status][actions-badge]][actions-link]
+[![Documentation status badge](https://readthedocs.org/projects/cloudcasting/badge/?version=latest)](https://cloudcasting.readthedocs.io/en/latest/?badge=latest)
 [![PyPI version][pypi-version]][pypi-link]
 [![PyPI platforms][pypi-platforms]][pypi-link]
 
-Tooling and infrastructure to enable cloud nowcasting.
+Tooling and infrastructure to enable cloud nowcasting. Full documentation can be found at https://cloudcasting.readthedocs.io/.
 
 ## Linked model repos
 - [Optical Flow (Farneback)](https://github.com/alan-turing-institute/ocf-optical-flow)

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)

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

docs/source/conf.py

@@ -0,0 +1,49 @@
+# 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
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+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
+
+project = "cloudcasting"
+copyright = "2025, cloudcasting Maintainers"
+author = "cloudcasting Maintainers"
+release = "0.6"
+version = "0.6.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "m2r2",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"

docs/source/dataset.rst

@@ -0,0 +1,6 @@
+Dataset
+=======
+
+.. automodule:: cloudcasting.dataset
+   :members:
+   :special-members: __init__

docs/source/download.rst

@@ -0,0 +1,5 @@
+Download
+========
+
+.. automodule:: cloudcasting.download
+   :members:

docs/source/index.rst

@@ -0,0 +1,34 @@
+
+Documentation for cloudcasting
+==============================
+
+Tooling and infrastructure to enable cloud nowcasting.
+Check out the :doc:`usage` section for further information on how to install and run this package.
+
+This tool was developed by `Open Climate Fix <https://openclimatefix.org/>`_ and
+`The Alan Turing Institute <https://www.turing.ac.uk/>`_ as part of the
+`Manchester Prize <https://manchesterprize.org/>`_.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   dataset
+   download
+   metrics
+   models
+   utils
+   validation
+
+License
+-------
+
+The cloudcasting software is released under an `MIT License <https://github.com/alan-turing-institute/cloudcasting/blob/main/LICENSE>`_.
+
+Index
+-----
+
+* :ref:`genindex`

docs/source/metrics.rst

@@ -0,0 +1,5 @@
+Metrics
+=======
+
+.. automodule:: cloudcasting.metrics
+   :members:

docs/source/models.rst

@@ -0,0 +1,5 @@
+Models
+======
+
+.. automodule:: cloudcasting.models
+   :members:

docs/source/usage.md

@@ -0,0 +1,67 @@
+.. _usage:
+
+User guide
+==========
+
+**Contents:**
+
+- :ref:`install`
+- :ref:`optional`
+- :ref:`getting_started`
+
+.. _install:
+
+Installation
+------------
+
+To use cloudcasting, first install it using pip:
+
+```bash
+git clone https://github.com/alan-turing-institute/cloudcasting
+cd cloudcasting
+python -m pip install .
+```
+
+.. _optional:
+
+Optional dependencies
+---------------------
+
+cloudcasting supports optional dependencies, which are not installed by default. These dependencies are required for certain functionality.
+
+To run the metrics on GPU:
+
+```bash
+python -m pip install --upgrade "jax[cuda12]"
+```
+
+To make changes to the library, it is necessary to install the extra `dev` dependencies, and install pre-commit:
+
+```bash
+python -m pip install ".[dev]"
+pre-commit install
+```
+
+To create the documentation, it is necessary to install the extra `doc` dependencies:
+
+```bash
+python -m pip install ".[doc]"
+```
+
+.. _getting_started:
+
+Getting started
+---------------
+
+Use the command line interface to download data:
+
+```bash
+cloudcasting download "2020-06-01 00:00" "2020-06-30 23:55" "path/to/data/save/dir"
+```
+
+Once you have developed a model, you can also validate the model, calculating a set of metrics with a standard dataset.
+To make use of the cli tool, use the [model github repo template](https://github.com/alan-turing-institute/ocf-model-template) to structure it correctly for validation.
+
+```bash
+cloudcasting validate "path/to/config/file.yml" "path/to/model/file.py"
+```

docs/source/utils.rst

@@ -0,0 +1,5 @@
+Utils
+=====
+
+.. automodule:: cloudcasting.utils
+   :members:

docs/source/validation.rst

@@ -0,0 +1,5 @@
+Validation
+==========
+
+.. automodule:: cloudcasting.validation
+   :members:

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 name = "cloudcasting"
 dynamic = ["version"]
 authors = [
-  { name = "cloudcasting Maintainers", email = "nsimpson@turing.ac.uk" },
+  { name = "cloudcasting Maintainers", email = "clouds@turing.ac.uk" },
 ]
 description = "Tooling and infrastructure to enable cloud nowcasting."
 readme = "README.md"
@@ -58,6 +58,11 @@ dev = [
   "scikit-image",
   "typeguard",
 ]
+doc = [
+  "sphinx",
+  "sphinx-rtd-theme",
+  "m2r2"
+]
 
 [tool.setuptools.package-data]
 "cloudcasting" = ["data/*.zip"]