docs: migrate to Material for MkDocs, overhaul README and guides

[MarcelRosier]

Summary

Migrate docs from Sphinx/Furo to Material for MkDocs, overhaul README, and restructure guides to be more approachable for new users.

What changed

Docs migration (Sphinx → Material for MkDocs)

• Material for MkDocs with light/dark mode, instant navigation, search, and code copy
• Auto-generated API docs via mkdocstrings from source code docstrings
• Jupyter notebook rendering via mkdocs-jupyter
• Reusable algorithm table snippets with pymdownx.snippets
• Restructured nav: Getting Started → Using BraTS → Prerequisites → Reference → Citation

README overhaul

• Prominent Documentation card grid at the top linking to quickstart and all task guides

Why

• The old docs was just an api doc, readme had cluttered usage instructions
• README was cluttered with info that belongs in the full docs
• Material for MkDocs gives a cleaner browsing experience with better search, responsive nav, and auto-generated API docs

Test locally

uv sync --group docs
uv run mkdocs serve

Open http://localhost:8000

[Copilot]

Pull request overview

This PR migrates the documentation stack from Sphinx/Furo to Material for MkDocs, restructures the docs into task-focused guides with reusable snippets and API reference pages, and significantly simplifies the repository README to funnel users into the new docs.

Changes:

• Replaced Sphinx-based docs with MkDocs Material, including mkdocstrings-powered API pages and mkdocs-jupyter notebook rendering.
• Reworked docs IA/navigation (Getting Started / Guides / Prerequisites / Reference / Citation) and introduced reusable algorithm table snippets.
• Overhauled README to a shorter “docs-first” entry point with quick links and a minimal example.

Reviewed changes

Copilot reviewed 43 out of 48 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Replaces long in-README task docs with a docs landing grid, simpler install/example, and shorter citation/contributing sections.
pyproject.toml	Swaps Sphinx doc dependencies for MkDocs Material + mkdocstrings + mkdocs-jupyter + revision-date plugin.
mkdocs.yml	Adds MkDocs Material configuration (theme, plugins, extensions) and new site navigation.
.readthedocs.yaml	Switches Read the Docs build from Sphinx to MkDocs using mkdocs.yml.
.pre-commit-config.yaml	Adjusts YAML hook configuration to avoid failing on mkdocs.yml tags.
.gitignore	Ignores MkDocs build output directory (site/).
docs/index.md	New MkDocs home page with quick install/example and navigation cards.
docs/assets/logo.svg	Adds logo used by MkDocs theme.
docs/getting-started/installation.md	New install page (pip + container runtime setup).
docs/getting-started/quickstart.md	New quickstart covering segmentation/inpainting/missing MRI with default constructors.
docs/guides/segmentation.md	New segmentation guide with examples and included algorithm-table snippets + batch section.
docs/guides/inpainting.md	New inpainting guide with example + batch section + algorithm-table snippet.
docs/guides/missing-mri.md	New missing-MRI guide with example + batch section + algorithm-table snippet.
docs/guides/preprocessing.md	New preprocessing guide describing atlas requirements and helper wrappers.
docs/guides/backends.md	New Docker/Singularity backend guide including GPU caveats.
docs/reference/algorithms.md	New reference page that assembles per-task algorithm-table snippets.
docs/reference/api/core.md	New mkdocstrings API page for core modules.
docs/reference/api/constants.md	New mkdocstrings API page for constants.
docs/reference/api/exceptions.md	New mkdocstrings API page for exceptions.
docs/reference/api/logging.md	New mkdocstrings API page for logging.
docs/snippets/algorithm-tables/adult-glioma-pre-post.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/adult-glioma-pre-treatment.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/africa.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/meningioma.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/meningioma-rt.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/metastases.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/pediatric.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/goat.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/inpainting.md	New reusable algorithm table snippet.
docs/snippets/algorithm-tables/missing-mri.md	New reusable algorithm table snippet.
docs/tutorials/utils.py	Adds tutorial visualization helpers for MRI modalities and outputs.
docs/citation.md	Adds dedicated citation page (narrative + BibTeX + CITATION.cff pointer).
docs/Makefile	Removes Sphinx build Makefile.
docs/make.bat	Removes Sphinx build batch script.
docs/source/conf.py	Removes Sphinx configuration.
docs/source/index.rst	Removes Sphinx index/toctree entry point.
docs/source/readme.rst	Removes Sphinx README include page.
docs/source/preprocess_readme.py	Removes README preprocessing script for Sphinx/MyST admonitions.
docs/source/core/core.rst	Removes Sphinx core toctree.
docs/source/core/segmentation_algorithms.rst	Removes Sphinx automodule page.
docs/source/core/inpainting_algorithms.rst	Removes Sphinx automodule page.
docs/source/core/missing_mri_algorithms.rst	Removes Sphinx automodule page.
docs/source/core/brats_algorithm.rst	Removes Sphinx automodule page.
docs/source/utils/utils.rst	Removes Sphinx utils page.
docs/source/utils/logging.rst	Removes Sphinx logging page.

Suppressed comments (1)

docs/getting-started/installation.md:9

• Add a small note inside the install snippet so readers immediately see that the preprocessing extra is Python >= 3.10 only.

pip install brats
pip install brats[preprocessing]

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.