From 08fa7f1f6ed6346899f1a9960bcb2d4669a07f25 Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Sun, 22 Feb 2026 19:52:04 +0530 Subject: [PATCH 1/7] Add structured Sphinx-based documentation scaffold (issue #61) --- .gitignore | 3 ++ docs/Makefile | 20 +++++++++ docs/make.bat | 35 +++++++++++++++ docs/source/api.rst | 57 +++++++++++++++++++++++++ docs/source/conf.py | 82 ++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 21 +++++++++ docs/source/installation.rst | 47 +++++++++++++++++++++ docs/source/introduction.rst | 20 +++++++++ 8 files changed, 285 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/introduction.rst diff --git a/.gitignore b/.gitignore index 358df4c25..6189d20eb 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/ \ No newline at end of file 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/source/api.rst b/docs/source/api.rst new file mode 100644 index 000000000..4e4908ca0 --- /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 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..f63b1d2ed --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,82 @@ +# 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 + +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 = [] + +# -- 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'] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..737a68f91 --- /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 \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 000000000..6fd71f09b --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,47 @@ +Installation +============ + +Basic Installation +------------------ + +Clone the repository: + +.. code-block:: bash + + git clone https://github.com/mllam/neural-lam.git + cd neural-lam + +Create a virtual environment and install in editable mode: + +.. code-block:: bash + + python -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + pip install -e . + +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: + +.. code-block:: bash + + cd docs + python -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + pip install -r requirements.txt + make html + +The generated HTML files will be available in: + +``docs/build/html/`` \ No newline at end of file diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 000000000..4585ea1e8 --- /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. \ No newline at end of file From 71bf2a805a75853e805c3b3e8895bdec90c8e8dd Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Mon, 23 Feb 2026 09:50:07 +0530 Subject: [PATCH 2/7] Refine installation instructions and remove requirements.txt reference --- docs/source/installation.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 6fd71f09b..e66d198d1 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -4,6 +4,8 @@ Installation Basic Installation ------------------ +Neural-LAM uses PDM for dependency management. + Clone the repository: .. code-block:: bash @@ -11,13 +13,11 @@ Clone the repository: git clone https://github.com/mllam/neural-lam.git cd neural-lam -Create a virtual environment and install in editable mode: +Install dependencies: .. code-block:: bash - python -m venv .venv - source .venv/bin/activate # On Windows: .venv\Scripts\activate - pip install -e . + pdm install Note ---- @@ -32,15 +32,13 @@ Refer to ``pyproject.toml`` for the full dependency list. Building the Documentation -------------------------- -To build the documentation locally: +To build the documentation locally, ensure the required documentation tools are installed (e.g., Sphinx, Furo, myst-parser). + +Then run: .. code-block:: bash - cd docs - python -m venv .venv - source .venv/bin/activate # On Windows: .venv\Scripts\activate - pip install -r requirements.txt - make html + sphinx-build -b html docs/source docs/build The generated HTML files will be available in: From f467d77280b5fbf6f662bee2a1928d5fafc1b20f Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Tue, 24 Feb 2026 14:56:41 +0530 Subject: [PATCH 3/7] Add CI docs workflow and ReadTheDocs integrating --- .github/workflows/docs.yml | 22 ++++++++++++++++++++++ .readthedocs.yaml | 16 ++++++++++++++++ docs/source/installation.rst | 15 ++++++++++++--- pyproject.toml | 1 + 4 files changed, 51 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 .readthedocs.yaml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..68ebce168 --- /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 pip install --system -e ".[docs]" + + - name: Build docs + run: sphinx-build -b html docs/source docs/build/html \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..603309721 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +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 diff --git a/docs/source/installation.rst b/docs/source/installation.rst index e66d198d1..35ae6e5d7 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,10 +1,19 @@ Installation ============ -Basic Installation +Install from PyPI ------------------ -Neural-LAM uses PDM for dependency management. +For standard use: + +.. code-block:: bash + + pip install neural_lam + +Basic Installation (Development) +-------------------------------- + +Neural-LAM uses `uv `_ for dependency management. Clone the repository: @@ -17,7 +26,7 @@ Install dependencies: .. code-block:: bash - pdm install + uv sync Note ---- 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"] From a083c8f4f5685056aad596c4885e858eec378e20 Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Tue, 24 Feb 2026 15:16:45 +0530 Subject: [PATCH 4/7] Fix pre-commit linting issues in docs and workflow files --- .github/workflows/docs.yml | 5 +++-- docs/source/api.rst | 3 ++- docs/source/conf.py | 17 +++++++++-------- docs/source/index.rst | 3 ++- docs/source/installation.rst | 2 +- docs/source/introduction.rst | 2 +- 6 files changed, 18 insertions(+), 14 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 68ebce168..5e6e17b07 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -16,7 +16,8 @@ jobs: uses: astral-sh/setup-uv@v5 - name: Install docs dependencies - run: uv pip install --system -e ".[docs]" + run: uv sync --group docs - name: Build docs - run: sphinx-build -b html docs/source docs/build/html \ No newline at end of file + run: sphinx-build -b html docs/source docs/build/html + \ No newline at end of file diff --git a/docs/source/api.rst b/docs/source/api.rst index 4e4908ca0..11225f96a 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -54,4 +54,5 @@ Training Training Utilities ~~~~~~~~~~~~~~~~~~ -.. automodule:: neural_lam.train_model \ No newline at end of file +.. automodule:: neural_lam.train_model + \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index f63b1d2ed..69d3b3ef0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -8,6 +8,7 @@ import os import sys + sys.path.insert(0, os.path.abspath("../../")) # Mock heavy scientific and ML dependencies so documentation @@ -43,10 +44,10 @@ "parse", ] -project = 'Neural-LAM' -copyright = '2026, MLLAM Contributors' -author = 'MLLAM Contributors' -release = '0.0.0' +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 @@ -72,11 +73,11 @@ "show-inheritance": True, } -templates_path = ['_templates'] -exclude_patterns = [] +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'] \ No newline at end of file +html_theme = "furo" +html_static_path = ["_static"] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 737a68f91..bfee8f9b9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,4 +18,5 @@ Contents introduction installation - api \ No newline at end of file + api + \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 35ae6e5d7..4275d0b51 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -51,4 +51,4 @@ Then run: The generated HTML files will be available in: -``docs/build/html/`` \ No newline at end of file +``docs/build/html/`` diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 4585ea1e8..374a6e870 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -17,4 +17,4 @@ The repository includes: - Visualization tools for model diagnostics For full project background and research motivation, -refer to the main README and associated publications. \ No newline at end of file +refer to the main README and associated publications. From 3dba2dcfa66e5e33562b20a78a90cf148c40b6f1 Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Tue, 24 Feb 2026 15:29:57 +0530 Subject: [PATCH 5/7] Fix line endings and pre-commit linting issues --- .github/workflows/docs.yml | 1 - .gitignore | 2 +- docs/source/api.rst | 1 - docs/source/conf.py | 3 ++- docs/source/index.rst | 1 - 5 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5e6e17b07..bde90de8d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,4 +20,3 @@ jobs: - name: Build docs run: sphinx-build -b html docs/source docs/build/html - \ No newline at end of file diff --git a/.gitignore b/.gitignore index 6189d20eb..431841aba 100644 --- a/.gitignore +++ b/.gitignore @@ -90,4 +90,4 @@ pdm.lock tests/test_outputs/ ### Sphinx ### -docs/build/ \ No newline at end of file +docs/build/ diff --git a/docs/source/api.rst b/docs/source/api.rst index 11225f96a..d8eb13dad 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -55,4 +55,3 @@ Training Utilities ~~~~~~~~~~~~~~~~~~ .. automodule:: neural_lam.train_model - \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 69d3b3ef0..e352d163e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,6 +6,7 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +# Standard library import os import sys @@ -80,4 +81,4 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "furo" -html_static_path = ["_static"] \ No newline at end of file +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst index bfee8f9b9..fe001969f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,4 +19,3 @@ Contents introduction installation api - \ No newline at end of file From deda354cd9e3d95c0031074e2a60a2d75c928698 Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Tue, 24 Feb 2026 15:40:33 +0530 Subject: [PATCH 6/7] Fix sphinx-build not found by using uv run --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bde90de8d..65215afa1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,4 +19,4 @@ jobs: run: uv sync --group docs - name: Build docs - run: sphinx-build -b html docs/source docs/build/html + run: uv run sphinx-build -b html docs/source docs/build/html From 063bc15ccb23b93b60f254172a26a6bd5714a9ef Mon Sep 17 00:00:00 2001 From: Penmatsa Tanoj Pavan Surya Varma Date: Fri, 27 Feb 2026 21:49:14 +0530 Subject: [PATCH 7/7] Fix ReadTheDocs and Add docs/requirements.txt --- .readthedocs.yaml | 3 ++- docs/requirements.txt | 3 +++ 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 603309721..644247e7f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,4 +13,5 @@ python: - method: pip path: . extra_requirements: - - docs + - docs + - requirements: docs/requirements.txt 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