docs: implement Sphinx-Autodoc harness and fix ARModel docstring form…

[alphaleporus]

Describe your changes

Summary of the changes:
This PR implements a working Sphinx-Autodoc proof-of-concept (POC) to demonstrate the viability of runtime introspection for the neural-lam documentation pipeline. It successfully captures the PyTorch Lightning lifecycle hooks in ARModel and the @property decorators in the datastore abstraction layer. Additionally, it fixes existing docstring formatting errors (unexpected unindents) in ARModel that were exposed once introspection was enabled.

Motivation and context:
As discussed in the #gsoc-project2 channel, building a robust documentation pipeline for neural-lam requires handling a decorator-heavy, pure Python architecture. Static analysis tools (like AutoAPI) struggle to capture runtime-injected attributes and PyTorch Lightning hooks without heavy manual intervention.

This POC proves that Autodoc (runtime introspection) is the correct architectural choice. To ensure this pipeline will survive in a lightweight, CPU-only CI/CD environment (e.g., GitHub Actions), I implemented a two-tier mocking strategy:

1. Standard Mocking: Configured autodoc_mock_imports for heavy ML dependencies (torch, pytorch_lightning, xarray, etc.) to preserve class inheritance visibility.
2. Aggressive Override (MagicMock): Implemented a custom sys.modules override specifically for mlflow and tueplots. Standard string-mocking causes Sphinx to crash when parsing Python 3.10+ union type hints (e.g., list | np.ndarray) in the logger modules, or when executing module-level plotting math. This setup securely bypasses those execution conflicts while preserving the real numpy base.

Dependencies:

• Added sphinx, sphinx-rtd-theme, and sphinx-autodoc-typehints to pyproject.toml [dev-dependencies] via PDM.

Issue Link

Relates to #61, #69

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 (Fixed existing formatting errors in ARModel docstrings)
• I have placed in-line comments to clarify the intent of any hard-to-understand passages of my code (Added detailed comments in conf.py explaining the mocking strategy)
• 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.

[sadamov]

I am closin this PR because it solves more than one issue. Also, the work on the autodocs is being discused here #196 #230 please contribute there instead. If you think the ar_model error is worth persuing further, please open a separate PR with issue and original PR template.

[alphaleporus]

Hi @sadamov, completely understood! Apologies for combining the infrastructure POC with the docstring fixes; I will make sure to keep future PRs strictly scoped to single issues following the original template. I'll open a separate, clean PR just for the ar_model.py formatting fixes, and I will move my architectural findings regarding Autodoc vs. AutoAPI over to the discussion in #196/#230. Thanks for pointing me in the right direction!