Update docs

[robin-janssen]

Documentation overhaul:

• Everything in one place
• Explanations around how to use and contribute
• Notebook with exemplary benchmark run
• Added resolve_storage_backend so users can start with a simple SQLite file (path configurable) while keeping Postgres as the default for multi-user setups.

[github-actions]

📚 Docs preview: https://AstroAI-Lab.github.io/CODES-Benchmark/pr-54/

[Copilot]

Pull request overview

This PR restructures and expands the project documentation (Sphinx + MyST-NB), while also introducing several functional changes across tuning/training/evaluation utilities, CI docs deployment, and configuration handling.

Changes:

• Rebuild Sphinx docs under docs/source/ with new guides, references, and a MyST-NB tutorials section.
• Update tuning/training/eval/benchmark code for more robust config defaults/access patterns, plus new Optuna storage backend resolution.
• Update CI to build/deploy docs via GitHub Pages and add/configure formatting + dependency tooling.

Reviewed changes

Copilot reviewed 63 out of 89 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
test/test_utils.py	Import reordering to match updated utilities usage.
test/test_training_pipeline.py	Import ordering cleanup.
test/test_bench_main.py	Update compute test to handle CUDA requirements and new memory-footprint signature.
run_tuning.py	Add storage backend resolution (sqlite/postgres), apply tuning defaults, and adjust tuning behavior.
run_training.py	Add CUDA debug print (currently unsafe on CPU-only).
run_eval.py	Make compare optional via .get(...) and add completion message.
requirements.txt	Large dependency refresh via freeze (currently includes non-portable editable path).
pyproject.toml	Add docs-related dev dependencies (myst-nb, linkify-it-py).
docs/source/tutorials/index.md	Add tutorials landing page and local execution instructions.
docs/source/reference/datasets.md	Add dataset catalog page (includes generated table).
docs/source/reference/configuration.md	Add config reference and defaults documentation.
docs/source/reference/_datasets_table.rst	Add generated datasets table.
docs/source/index.rst	New documentation home page / toctrees.
docs/source/guides/running-benchmarks/uncertainty.md	New UQ guide.
docs/source/guides/running-benchmarks/tuning.md	New Optuna tuning guide.
docs/source/guides/running-benchmarks/training.md	New training guide.
docs/source/guides/running-benchmarks/modalities.md	New modalities guide.
docs/source/guides/running-benchmarks/index.md	New running-benchmarks hub page.
docs/source/guides/running-benchmarks/evaluation.md	New evaluation guide.
docs/source/guides/running-benchmarks/architectures.md	New baseline architectures overview.
docs/source/guides/running-benchmarks/accuracy-metrics.md	New accuracy-metrics guide.
docs/source/guides/extending-benchmark.md	New extension guide (datasets/surrogates).
docs/source/getting-started.md	New getting started page.
docs/source/conf.py	New Sphinx config (MyST-NB, dataset table generation, theme tweaks).
docs/source/codes.utils.rst	RST formatting/ordering tweaks for autodoc.
docs/source/codes.tune.rst	New package RST for codes.tune.
docs/source/codes.train.rst	RST formatting/ordering tweaks for autodoc.
docs/source/codes.surrogates.rst	Add surrogate subpackage toctree and adjust module exposure.
docs/source/codes.surrogates.LatentPolynomial.rst	New subpackage RST.
docs/source/codes.surrogates.LatentNeuralODE.rst	New subpackage RST.
docs/source/codes.surrogates.FCNN.rst	New subpackage RST.
docs/source/codes.surrogates.DeepONet.rst	New subpackage RST.
docs/source/codes.surrogates.AbstractSurrogate.rst	New subpackage RST.
docs/source/codes.rst	Mark orphan / adjust top-level codes page content.
docs/source/codes.benchmark.rst	RST formatting/ordering tweaks for autodoc.
docs/source/api-reference.md	New API reference overview page.
docs/source/_templates/napoleon/raises.rst_t	Custom napoleon template.
docs/source/_templates/napoleon/params.rst_t	Custom napoleon template.
docs/source/_templates/napoleon/attrs.rst_t	Custom napoleon template.
docs/source/_static/file-alt-solid.svg	Add static icon asset.
docs/source/_static/file-alt-solid-white.svg	Add static icon asset (white).
docs/source/_static/favicon-96x96.png	Add favicon asset.
docs/source/_static/book-solid.svg	Add static icon asset.
docs/source/_static/book-solid-white.svg	Add static icon asset (white).
docs/index.rst	Remove old docs index (migrated to docs/source).
docs/conf.py	Remove old Sphinx config (migrated to docs/source/conf.py).
datasets/data_sources.yaml	Normalize YAML formatting and entries.
datasets/_data_analysis/__init__.py	Fix trailing comma formatting in export list.
configs/tuning/sqlite_quickstart.yaml	Add SQLite quickstart tuning config example.
configs/train_eval/config_minimal_evals.yaml	Add minimal config example with evaluation switches.
configs/train_eval/config_minimal.yaml	Add minimal config example.
configs/train_eval/config_full.yaml	Add full template config example.
config_full.yaml	Remove old root-level full config example (moved to configs/).
config.yaml	Remove old root-level config example (moved to configs/).
codes/utils/data_utils.py	Make dataset info printing more robust when attrs are missing.
codes/tune/tune_utils.py	Add workspace/config prompting and apply_tuning_defaults.
codes/tune/optuna_fcts.py	Use safer dataset config defaults and seed handling.
codes/tune/__init__.py	Export apply_tuning_defaults.
codes/train/train_fcts.py	Safer .get(...) config access, subset_factor support, docstrings.
codes/train/__init__.py	Reorder exports.
codes/surrogates/FCNN/fcnn.py	Improve docstrings/type hints for collate/dataset.
codes/surrogates/DeepONet/don_utils.py	Remove TODO and improve docstring formatting.
codes/surrogates/AbstractSurrogate/abstract_surrogate.py	Whitespace cleanup.
codes/surrogates/AbstractSurrogate/abstract_config.py	Change default activation/loss handling (currently has SmoothL1Loss bug).
codes/benchmark/bench_utils.py	Make config access safer; change memory profiling API (return type annotation mismatch).
codes/benchmark/bench_plots.py	Make config access safer; docstring improvements.
codes/benchmark/bench_fcts.py	Make config access safer; adjust compute evaluation to skip/handle CUDA profiling.
README.md	Replace long narrative with concise quickstart + docs/contrib pointers (docs build command needs update).
.pre-commit-config.yaml	Add Black/isort hooks (versions currently mismatch repo’s pinned deps).
.github/workflows/ci.yaml	Add docs build/deploy steps and PR preview comments (publish_dir currently mismatched with build output).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 63 out of 89 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

codes/benchmark/bench_utils.py:290

• measure_memory_footprint’s docstring claims the model is moved back to its original device, but the function never restores it (it leaves the model on the provided CUDA device). Either restore the original device before returning or update the docstring to match the actual behavior to avoid surprising callers.

    Returns:
        tuple[dict, torch.nn.Module]: Dictionary with ``model_memory``, ``forward_memory``,
        ``backward_memory``, and ``forward_memory_nograd`` plus the model (moved back to its
        original device).
    """
    # Determine the target device
    if not torch.cuda.is_available() or device.type != "cuda":
        raise RuntimeError("CUDA device required for memory profiling.")

    model.to("cpu")

    torch.cuda.synchronize(device)
    torch.cuda.reset_peak_memory_stats(device)
    before_load = torch.cuda.memory_allocated(device)

    model.to(device)
    torch.cuda.synchronize(device)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 63 out of 89 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.