Add structured Sphinx-based documentation scaffold (issue #61)

[varma1221]

Describe your changes

This PR introduces a structured Sphinx-based documentation scaffold for Neural-LAM, addressing #61.

The idea was to build something that can actually grow rather than just showing that Sphinx works. The documentation is organized into clear sections (introduction, installation, api) and uses Sphinx with autodoc, napoleon, and myst_parser to generate API documentation directly from existing docstrings.

Instead of documenting only the top-level package, this PR documents modules explicitly (interaction_net, metrics, utils, vis, models, datastore, weather_dataset, train_model) making it easier to add new modules later.

The configuration enables documentation builds without requiring the full ML training environment by using autodoc_mock_imports for heavy scientific and ML dependencies.

While integrating Sphinx, module-level import side effects were observed (e.g., path construction and runtime-dependent operations). These may produce warnings during documentation builds. This PR does not modify core module behavior but establishes a stable documentation structure.

Documentation Dependencies

The following are required only for building documentation:

• sphinx
• furo
• myst-parser

These do not affect runtime training dependencies.

---

Issue Link

addresses #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 (I do not have write access)

---

Checklist for reviewers

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

• the code is readable
• the changes are easy to maintain

---

Author checklist after completed review

• I have added a line to the CHANGELOG describing this change

---

Checklist for assignee

• PR is up to date with the base branch
• the tests pass
• (if applicable) the PR is assigned to the next milestone
• author has added an entry to the changelog

[varma1221]

Hi @joeloskarsson and @leifdenby
I’ve added a structured Sphinx documentation scaffold addressing #61. I’d appreciate feedback on whether this direction aligns with the intended documentation roadmap. If appropriate, could you please assign a reviewer?

[leifdenby]

Thank you for working on this @varma1221! Could you upload the resulting output somewhere so I could take a look? It would also be great if you could look into how to get this integrated with a ci action so that we can automatically push the rendered docs to readthedocs for example. I have tried to look at this before, but didn't finish it... The ideal would be that each PR had its own temporary URL where the rendered docs can be viewed. Is that possible?

[varma1221]

Thank you so much for the feedback, @leifdenby.
I've zipped up the locally rendered docs/build/html folder and attached it directly to this comment so you can take a look at the output.
neural_lam_docs_preview.zip

Before I start on the CI integration, I want to make sure I understand the preferred setup. Is there already a ReadTheDocs project configured for neural-lam, or would creating that foundation (like a .readthedocs.yaml file) be part of this PR?

I ask because enabling per-PR preview URLs requires access to the ReadTheDocs admin dashboard, so I want to know what's already in place before wiring up the workflow.

[varma1221]

Hi @leifdenby, I've pushed the CI and Read the Docs integration.

• .readthedocs.yml configures Read the Docs to build the Sphinx documentation.
• .github/workflows/docs.yml validates the docs build on every push and pull request, so issues like broken docstrings or missing imports are caught early. It uses uv, consistent with the rest of the project.

Once the repository is connected on Read the Docs and pull request builds are enabled, each PR should automatically receive its own temporary preview URL via RTD's PR build feature.

Let me know if this setup aligns with what you had in mind, and I'm happy to adjust if needed.

[sadamov]

@Mohit-Lakra from #272 has a very similar implementation and is already hosting the docs on his github page. Do you think you could cooperate on this issue and find a common solution?

[varma1221]

Hi @sadamov, thanks for the heads up. I've had a look at @Mohit-Lakra's PR #272 and his live demo - the sphinx-autoapi approach is technically stronger, particularly since it avoids the need to mock heavy dependencies at build time.

I'm happy to collaborate. @Mohit-Lakra, would it make sense to make it combine efforts? I could contribute the .readthedocs.yaml and CI workflow from this PR into your branch, and we can consolidate on the Jupyter Book + sphinx-autoapi stack. Let me know how you'd like to proceed.

[Mohit-Lakra]

hey @varma1221 — yeah that makes sense, the autoapi approach sidesteps the whole mock imports headache. your readthedocs config is solid though and the per-PR preview URL thing is something leif specifically asked about so it'd be good to bring that in. if you want to just send it over i'll integrate it and add you to the changelog, or we can figure out the best way to combine — either works for me 🙌

[varma1221]

Following up - coordinating with @Mohit-Lakra to port the .readthedocs.yaml and CI workflow into his branch (#272). Will close this PR once that contribution is in place.

[sadamov]

@varma1221 just doing some housekeeping. Did you complete your contribution to #272 so that this PR can be closed, or not yet?

[varma1221]

Hi @sadamov yes, the .readthedocs.yaml from this PR was contributed to #272. Happy for this to be closed