diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..65215afa1 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,22 @@ +name: Docs + +on: [push, pull_request] + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install uv + uses: astral-sh/setup-uv@v5 + + - name: Install docs dependencies + run: uv sync --group docs + + - name: Build docs + run: uv run sphinx-build -b html docs/source docs/build/html diff --git a/.gitignore b/.gitignore index 358df4c25..431841aba 100644 --- a/.gitignore +++ b/.gitignore @@ -88,3 +88,6 @@ __MACOSX # exclude pdm.lock file so that both cpu and gpu versions of torch will be accepted by pdm pdm.lock tests/test_outputs/ + +### Sphinx ### +docs/build/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..644247e7f --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,17 @@ +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/source/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - docs + - requirements: docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /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 000000000..dc1312ab0 --- /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/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..89a547c71 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=7.0 +furo>=2024.1.29 +myst-parser>=3.0 diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 000000000..d8eb13dad --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,57 @@ +API Reference +============= + +Core Components +--------------- + +Interaction Network +~~~~~~~~~~~~~~~~~~~ + +.. automodule:: neural_lam.interaction_net + +Metrics +~~~~~~~ + +.. automodule:: neural_lam.metrics + +Utilities +~~~~~~~~~ + +.. automodule:: neural_lam.utils + +Visualization +~~~~~~~~~~~~~ + +.. automodule:: neural_lam.vis + + +Model Architecture +------------------ + +Models +~~~~~~ + +.. automodule:: neural_lam.models + + +Data Handling +------------- + +Datastore +~~~~~~~~~ + +.. automodule:: neural_lam.datastore + +Weather Dataset +~~~~~~~~~~~~~~~ + +.. automodule:: neural_lam.weather_dataset + + +Training +-------- + +Training Utilities +~~~~~~~~~~~~~~~~~~ + +.. automodule:: neural_lam.train_model diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..e352d163e --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,84 @@ +# 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 + +# Standard library +import os +import sys + +sys.path.insert(0, os.path.abspath("../../")) + +# Mock heavy scientific and ML dependencies so documentation +# can be built without requiring the full runtime environment. +MOCK_MODULES = [ + "torch", + "torch.nn", + "torch.optim", + "torch.utils", + "torch_geometric", + "pytorch_lightning", + "mlflow", + "numpy", + "scipy", + "pandas", + "xarray", + "netCDF4", + "zarr", + "matplotlib", + "matplotlib.pyplot", + "seaborn", + "tueplots", + "wandb", + "sklearn", + "tqdm", + "yaml", + "loguru", + "dataclass_wizard", + "cartopy", + "cartopy.crs", + "mllam_data_prep", + "dask", + "parse", +] + +project = "Neural-LAM" +copyright = "2026, MLLAM Contributors" +author = "MLLAM Contributors" +release = "0.0.0" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "myst_parser", +] + +napoleon_google_docstring = True +napoleon_numpy_docstring = True +autosummary_generate = True +autodoc_preserve_defaults = True +autodoc_mock_imports = MOCK_MODULES +suppress_warnings = ["autodoc.import_object"] + +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, +} + +templates_path = ["_templates"] +exclude_patterns: list[str] = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..fe001969f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,21 @@ +Neural-LAM Documentation +======================== + +Neural-LAM is a graph-based, research-oriented framework for +Limited Area Model (LAM) data-driven weather forecasting. +It combines graph neural network architectures with structured +meteorological datasets to enable scalable regional forecasting +experiments. + +For project details and research context, see the +`Neural-LAM GitHub repository `_. + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + introduction + installation + api diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 000000000..4275d0b51 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,54 @@ +Installation +============ + +Install from PyPI +------------------ + +For standard use: + +.. code-block:: bash + + pip install neural_lam + +Basic Installation (Development) +-------------------------------- + +Neural-LAM uses `uv `_ for dependency management. + +Clone the repository: + +.. code-block:: bash + + git clone https://github.com/mllam/neural-lam.git + cd neural-lam + +Install dependencies: + +.. code-block:: bash + + uv sync + +Note +---- + +Neural-LAM depends on several scientific and machine learning +libraries (e.g., PyTorch, Cartopy, Dask). Depending on your use +case (training, visualization, data preparation), additional +dependencies may be required. + +Refer to ``pyproject.toml`` for the full dependency list. + +Building the Documentation +-------------------------- + +To build the documentation locally, ensure the required documentation tools are installed (e.g., Sphinx, Furo, myst-parser). + +Then run: + +.. code-block:: bash + + sphinx-build -b html docs/source docs/build + +The generated HTML files will be available in: + +``docs/build/html/`` diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 000000000..374a6e870 --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,20 @@ +Introduction +============ + +Neural-LAM is a research framework designed for data-driven +weather forecasting in Limited Area Models (LAMs). + +The project leverages graph neural networks to represent +structured spatial relationships between meteorological grid +points. This allows flexible modeling of regional weather systems +while maintaining scalability. + +The repository includes: + +- Graph-based neural network architectures +- Dataset abstractions for meteorological data +- Training and evaluation utilities +- Visualization tools for model diagnostics + +For full project background and research motivation, +refer to the main README and associated publications. diff --git a/pyproject.toml b/pyproject.toml index 55cd7642f..4c47de54c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,7 @@ requires-python = ">=3.10" [dependency-groups] dev = ["pre-commit>=3.8.0", "pytest>=8.3.2", "pooch>=1.8.2"] +docs = ["sphinx>=7.0", "furo>=2024.1.29", "myst-parser>=3.0"] [tool.setuptools] py-modules = ["neural_lam"]