docs: set up MkDocs documentation structure with mkdocstrings

[Sidhant185]

Describe your changes

Sets up MkDocs as the documentation system for neural-lam, following
the discussion in #61.

Changes introduced:

• mkdocs.yml at the repository root with MkDocs Material theme config
• docs/index.md — project overview and quick links
• docs/getting_started/installation.md — installation instructions
• docs/getting_started/quickstart.md — basic usage guide
• docs/api/metrics.md — auto-generated from neural_lam.metrics docstrings
• docs/api/models.md — auto-generated from model class docstrings
• docs/api/datastore.md — auto-generated from BaseDatastore docstrings
• pyproject.toml updated with new docs dependency group:
  mkdocs, mkdocs-material, mkdocstrings[python]

No code logic changes were made.

Issue Link

closes #456
relates to #61

Type of change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📖 Documentation (Addition or improvements to documentation)

Checklist before requesting a review

• My branch is up-to-date with the target branch
• I have performed a self-review of my code
• For any new/modified functions/classes I have added docstrings that clearly describe its purpose, expected inputs and returned values
• I have placed in-line comments to clarify the intent of any hard-to-understand passages of my code
• I have updated the README to cover introduced code changes
• I have added tests that prove my fix is effective or that my feature works
• I have given the PR a name that clearly describes the change, written in imperative form
• I have requested a reviewer and an assignee

Checklist for reviewers

Each PR comes with its own improvements and flaws. The reviewer should check the following:

• the code is readable
• the code is well tested
• the code is documented (including return types and parameters)
• the code is easy to maintain

Author checklist after completed review

• I have added a line to the CHANGELOG describing this change:
  • added: set up MkDocs documentation structure with mkdocstrings

Checklist for assignee

• PR is up to date with the base branch
• the tests pass
• (if the PR is not just maintenance/bugfix) the PR is assigned to the next milestone. If it is not, propose it for a future milestone.
• author has added an entry to the changelog (and designated the change as added, changed, fixed or maintenance)
• Once the PR is ready to be merged, squash commits and merge the PR.

[Seai5]

Hi @Sidhant185!

I tested it locally on my machine (Windows, Python venv with uv):

• Switched to this branch (git fetch + checkout pr-457-mkdocs)
• Installed mkdocs, mkdocs-material, mkdocstrings[python]
• Ran mkdocs serve → built successfully, no errors, site live at http://127.0.0.1:8000/

What I saw:

• Home page has clear intro, features list, and quick links — very welcoming for new users.
• Getting Started → Installation matches the README commands perfectly.
• Quickstart shows train_model example nicely.
• API Reference auto-generates pages for models (GraphLAM/HiLAM), metrics, datastore — pulls docstrings well.
• Material theme looks clean and modern.

Small notes/possible improvements:

• Some API pages might benefit from more complete docstrings (e.g., if a method has short/no description, it shows minimal info).
• Nav feels good, but maybe add a "Developer Guide" or "Architecture" section later for data → graph → model flow?

Excited about the related CI PRs (#461/#462) — auto-deploy to GitHub Pages would make this live and awesome.

happy to help add/fix a small page (e.g., a markdown diagram of workflow) or test CI workflow if useful.

Best,
hrithik

[Sidhant185]

Local Preview — Documentation Site

I have set up and tested this documentation system locally using
mkdocs serve. Below are screenshots of the rendered output.

Home Page

API Reference — Metrics

The metrics module is rendered with full NumPy-style parameter tables
showing Name, Type, Description and Default columns.

API Reference — Configuration

All configuration dataclasses (DatastoreSelection,
ManualStateFeatureWeighting, UniformFeatureWeighting,
OutputClamping, TrainingConfig, NeuralLAMConfig) are
auto-documented from their existing docstrings.

API Reference — Models

GraphLAM, HiLAM and HiLAMParallel are all rendered with
their class descriptions and method references, with direct links
to source code.

Changelog

The existing CHANGELOG.md is embedded directly into the docs
site via pymdownx.snippets, keeping it as a single source of truth.

Summary of changes in this PR

• mkdocs.yml with MkDocs Material theme and mkdocstrings config
• docs/ structure: Home, Getting Started, API Reference, Changelog
• NumPy-style docstrings added to metrics.py for clean rendering
• docs dependency group added to pyproject.toml
• Related CI workflow in ci: add GitHub Actions workflow to build and deploy MkDocs documentation #462 for automated GitHub Pages deployment

[Sidhant185]

Hi @HRITHIK, thank you so much for testing this on Windows and for
the detailed feedback - really appreciate it!

Totally agree with your notes:

• Docstrings: Yes, some methods have minimal descriptions right
  now. I am planning to improve docstrings across the core modules
  incrementally — PRs Add type hints to all functions in metrics.py #446 #447 (metrics.py) and docs: add missing NumPy-style docstrings to config.py #460 (config.py) are
  already part of that effort.

• Developer Guide / Architecture section: Love this idea! A page
  explaining the data → graph → model flow would be really helpful
  for new contributors. I will add this to the docs structure as the
  work progresses.

Would be great to collaborate on the workflow diagram page — feel
free to reach out on the MLLAM Slack if you want to coordinate!

Thanks again for the review 🙌

[Seai5]

Hi @HRITHIK, thank you so much for testing this on Windows and for the detailed feedback - really appreciate it!

Totally agree with your notes:

• Docstrings: Yes, some methods have minimal descriptions right
  now. I am planning to improve docstrings across the core modules
  incrementally — PRs Add type hints to all functions in metrics.py #446 #447 (metrics.py) and docs: add missing NumPy-style docstrings to config.py #460 (config.py) are
  already part of that effort.
• Developer Guide / Architecture section: Love this idea! A page
  explaining the data → graph → model flow would be really helpful
  for new contributors. I will add this to the docs structure as the
  work progresses.

Would be great to collaborate on the workflow diagram page — feel free to reach out on the MLLAM Slack if you want to coordinate!

Thanks again for the review

Thanks @Sidhant185 for the invite — yes, I'd love to collaborate on the workflow diagram / Developer Guide page!

Quick outline idea for the page (in docs/developer-guide.md or similar):

• Section 1: Data loading (xarray/MEPS → tensors)
• Section 2: Graph construction (multi-scale/hierarchical, rectangular/triangular)
• Section 3: Model forward (GraphLAM/HiLAM, message passing)
• Section 4: Training/evaluation loop (AR steps, loss)
• Simple Mermaid diagram (MkDocs can embed it with mermaid flowchart ... )

I can draft a first markdown version + basic flowchart if that's useful. In the meantime, happy to help with docstrings too (e.g., add/improve NumPy-style in config.py building on #460, or metrics.py to complement #446/#447 type hints).

I'll post in Slack

Looking forward to it!
hrithik

[sadamov]

This looks like a duplicate of #230 please contribute/review there directly