feat(docs): enhance documentation with grid layouts for framework and modeling sections

Author: cofin

docs/getting-started.rst

@@ -18,11 +18,39 @@ It's designed to work on its own or with your favorite web framework.
 
 We've built extensions for some of the most popular frameworks, so you can get the most out of Advanced Alchemy with minimal effort.
 
-* `Litestar <https://docs.litestar.dev/>`_
-* `FastAPI <https://fastapi.tiangolo.com/>`_
-* `Starlette <https://www.starlette.io/>`_
-* `Flask <https://flask.palletsprojects.com/>`_
-* `Sanic <https://sanicframework.org/>`_
+.. grid:: 1 1 2 2
+    :padding: 0
+    :gutter: 2
+
+    .. grid-item-card:: Litestar
+        :link: https://docs.litestar.dev/
+        :link-type: url
+
+        Async web framework with built-in Advanced Alchemy support
+
+    .. grid-item-card:: FastAPI
+        :link: https://fastapi.tiangolo.com/
+        :link-type: url
+
+        Modern async web framework with automatic API documentation
+
+    .. grid-item-card:: Starlette
+        :link: https://www.starlette.io/
+        :link-type: url
+
+        Lightweight async web framework and toolkit
+
+    .. grid-item-card:: Flask
+        :link: https://flask.palletsprojects.com/
+        :link-type: url
+
+        Lightweight sync web framework
+
+    .. grid-item-card:: Sanic
+        :link: https://sanicframework.org/
+        :link-type: url
+
+        High-performance async web framework
 
 If your framework is not listed, don't worry! Advanced Alchemy is designed to be modular and easily integrated with any Python web framework.
 `Join our Discord <https://discord.gg/dSDXd4mKhp>`_ and we'll help you get started.

docs/usage/frameworks/index.rst

@@ -16,11 +16,39 @@ Overview
 
 Advanced Alchemy provides framework-specific extensions for:
 
-- Litestar (async)
-- FastAPI (async)
-- Flask (sync)
-- Sanic (async)
-- Starlette (async)
+.. grid:: 1 1 2 2
+    :padding: 0
+    :gutter: 2
+
+    .. grid-item-card:: Litestar
+        :link: litestar
+        :link-type: doc
+
+        Async web framework integration
+
+    .. grid-item-card:: FastAPI
+        :link: fastapi
+        :link-type: doc
+
+        Async web framework integration
+
+    .. grid-item-card:: Flask
+        :link: flask
+        :link-type: doc
+
+        Sync web framework integration
+
+    .. grid-item-card:: Sanic
+        :link: https://sanicframework.org/
+        :link-type: url
+
+        Async web framework integration
+
+    .. grid-item-card:: Starlette
+        :link: https://www.starlette.io/
+        :link-type: url
+
+        Async web framework integration
 
 Framework Comparison
 ====================

docs/usage/modeling/index.rst

@@ -7,7 +7,34 @@ Advanced Alchemy enhances SQLAlchemy's modeling capabilities with production-rea
 Learning Path
 =============
 
+Follow this progression to master Advanced Alchemy modeling:
+
+.. grid:: 1 1 3 3
+    :gutter: 2
+
+    .. grid-item-card:: 1. Basics
+        :link: basics
+        :link-type: doc
+        :text-align: center
+
+        Core concepts and simple models
+
+    .. grid-item-card:: 2. Relationships
+        :link: relationships
+        :link-type: doc
+        :text-align: center
+
+        Connecting models together
+
+    .. grid-item-card:: 3. Advanced
+        :link: advanced
+        :link-type: doc
+        :text-align: center
+
+        Complex patterns and optimization
+
 .. toctree::
+   :hidden:
    :maxdepth: 1
 
    basics

docs/usage/repositories/index.rst

@@ -7,7 +7,34 @@ Advanced Alchemy's repository pattern provides a clean, consistent interface for
 Learning Path
 =============
 
+Follow this progression to master Advanced Alchemy repositories:
+
+.. grid:: 1 1 3 3
+    :gutter: 2
+
+    .. grid-item-card:: 1. Basics
+        :link: basics
+        :link-type: doc
+        :text-align: center
+
+        CRUD operations and simple queries
+
+    .. grid-item-card:: 2. Filtering
+        :link: filtering
+        :link-type: doc
+        :text-align: center
+
+        Pagination, sorting, and search
+
+    .. grid-item-card:: 3. Advanced
+        :link: advanced
+        :link-type: doc
+        :text-align: center
+
+        Bulk operations and custom queries
+
 .. toctree::
+   :hidden:
    :maxdepth: 1
 
    basics

docs/usage/services/index.rst

@@ -7,7 +7,34 @@ Services in Advanced Alchemy build upon repositories to provide higher-level bus
 Learning Path
 =============
 
+Follow this progression to master Advanced Alchemy services:
+
+.. grid:: 1 1 3 3
+    :gutter: 2
+
+    .. grid-item-card:: 1. Basics
+        :link: basics
+        :link-type: doc
+        :text-align: center
+
+        Service pattern and basic CRUD
+
+    .. grid-item-card:: 2. Schemas
+        :link: schemas
+        :link-type: doc
+        :text-align: center
+
+        Pydantic/msgspec integration
+
+    .. grid-item-card:: 3. Advanced
+        :link: advanced
+        :link-type: doc
+        :text-align: center
+
+        Complex operations and hooks
+
 .. toctree::
+   :hidden:
    :maxdepth: 1
 
    basics