Update docs (sqlachemy scalar column, items transformer) (#731)

Author: uriyyo

docs/integrations.md docs/integrations/integrations.mddocs/integrations.md renamed to docs/integrations/integrations.md

@@ -0,0 +1,35 @@
+# SQLAlchemy
+
+A minimal example of using the SQLAlchemy integration can be seen below:
+
+```python
+from sqlalchemy import select
+from fastapi_pagination.ext.sqlalchemy import paginate
+
+
+@app.get('/users', response_model=Page[UserOut])
+def get_users(db: Session = Depends(get_db)):
+    return paginate(db, select(User).order_by(User.created_at))
+```
+
+## Scalar column
+
+If you want to paginate a scalar column and return non-scalar value, then you will need to use `transformer`
+```python
+from sqlalchemy import select
+from fastapi_pagination.ext.sqlalchemy import paginate
+from pydantic import BaseModel
+
+
+class UserNameOut(BaseModel):
+    name: str
+
+    
+@app.get('/users', response_model=Page[UserNameOut])
+def get_user_names(db: Session = Depends(get_db)):
+    return paginate(
+        db,
+        select(User.name).order_by(User.created_at),
+        transformer=lambda items: [{"name": name} for name in items],
+    )
+```

docs/integrations/sqlalchemy.md

@@ -0,0 +1,11 @@
+# Items Transformer
+
+If you want to transform items before passing it to schema validation stage,
+you can use `transformer` argument of `paginate` function.
+
+```py hl_lines="13"
+{! ../docs_src/tutorial/items_transformer.py !}
+```
+
+`transformer` argument is a function that accepts a list of items and returns a list of items that will be passed to
+page schema validation stage.

docs/tutorials/items-transformer.md

@@ -0,0 +1,14 @@
+from fastapi import FastAPI
+
+from fastapi_pagination import Page, add_pagination, paginate
+
+app = FastAPI()
+add_pagination(app)
+
+
+@app.get("/double-nums")
+def get_double_nums() -> Page[int]:
+    return paginate(
+        [*range(1_000)],
+        transformer=lambda x: [i * 2 for i in x],
+    )

docs_src/tutorial/items_transformer.py

@@ -28,12 +28,15 @@ nav:
       - "Limit Offset Pagination": tutorials/limit-offset-pagination.md
       - "Links in Pagination": tutorials/links-pagination.md
       - "Cursor Pagination": tutorials/cursor-pagination.md
+      - "Items Transformer": tutorials/items-transformer.md
   - "Advanced User Guide":
       - "Custom Params": tutorials_advanced/custom-params.md
       - "Custom Page": tutorials_advanced/custom-page.md
       - "Custom Pagination Function": tutorials_advanced/custom-paginate.md
   - "Integrations":
+      - "Integrations": integrations/integrations.md
       - "Available Integrations": integrations/available-integrations.md
+      - "SQLAlchemy": integrations/sqlalchemy.md
   - "Contributing": contributing.md
   - "License": license.md