Update some usage documents (#27)

* Update some usage documents

* Update the theme color

Author: wu-clan

docs/advanced/commit.md

@@ -0,0 +1,39 @@
+SQLAlchemy CRUD Plus 内部很多方法都提供了 `commit` 参数，默认值为 `False`，它既不会执行提交操作，也不包含 `flush`
+等行为，要想真正写入到数据库，你可以通过以下几种方案
+
+## `commit=True`
+
+这通常适用于手动创建的 [session 生成器](https://fastapi.tiangolo.com/tutorial/sql-databases/?h=get_db#create-a-dependency),
+SQLAlchemy CRUD Plus 将在内部自动执行提交
+
+```py hl_lines="31"
+from fastapi import FastAPI, Depends
+
+--8<-- "docs/ext/get_db.py"
+
+app = FastAPI()
+
+
+class CreateIns(BaseModel):
+    # your pydantic schema
+    pass
+
+
+@app.post('/api', summary='新增一条数据')
+async def create(self, obj: CreateIns, db: AsyncSession = Depends(get_db)) -> None:
+    await self.create_model(db, obj, commit=True)
+```
+
+## `begin()`
+
+适用于自动提交，[这一切都由 sqlalchemy 在内部完成](https://docs.sqlalchemy.org.cn/en/20/orm/session_transaction.html)
+，因此，用户无需重复调用 commit 方法
+
+```py hl_lines="9"
+--8<-- "docs/ext/async_db_session.py"
+
+
+async def create(self, obj: CreateIns) -> None:
+    async with async_db_session.begin() as db:
+        await self.create_model(db, obj)
+```

docs/advanced/primary_key.md

@@ -9,7 +9,7 @@ async def delete(self, db: AsyncSession, primary_key: int) -> int:
 
 ## 主键定义
 
-!!! warning 自动主键
+!!! tip 自动主键
 
     我们在 SQLAlchemy CRUD Plus 内部通过 [inspect()](https://docs.sqlalchemy.org/en/20/core/inspection.html) 自动搜索表主键，
     而非强制绑定主键列必须命名为 id，感谢 [@DavidSche](https://github.com/DavidSche) 提供帮助 

docs/changelog.md

@@ -1,11 +1,5 @@
 # Change Logs
 
-* Prepare for 1.3.0 release. PR [#22](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/22) by [@wu-clan](https://github.com/wu-clan).
-* Add mor and **gor** filters . PR [#21](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/21) by [@wu-clan](https://github.com/wu-clan).
-* Prepare for 1.2.0 release. PR [#20](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/20) by [@wu-clan](https://github.com/wu-clan).
-* Add select and sort constructors. PR [#19](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/19) by [@wu-clan](https://github.com/wu-clan).
-* Add ci for change logs. PR [#18](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/18) by [@wu-clan](https://github.com/wu-clan).
-
 ## 1.4.0 - 2024-08-27
 
 ### What's Changed

docs/ext/async_db_session.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 
 async_engine = create_async_engine('数据库连接', future=True)

docs/ext/get_db.py

@@ -0,0 +1,18 @@
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+async_engine = create_async_engine('数据库连接', future=True)
+async_db_session = async_sessionmaker(async_engine, autoflush=False, expire_on_commit=False)
+
+
+async def get_db() -> AsyncSession:
+    """
+    session 生成器
+    """
+    session = async_db_session()
+    try:
+        yield session
+    except Exception as se:
+        await session.rollback()
+        raise se
+    finally:
+        await session.close()

docs/ext/model.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-

docs/index.md

@@ -20,6 +20,12 @@
     pdm add sqlalchemy-crud-plus
     ```
 
+=== "uv"
+
+    ```sh
+    uv add sqlalchemy-crud-plus
+    ```
+
 ## 示例
 
 === "api.py"

docs/installing.md

@@ -18,3 +18,9 @@
     ```sh
     pdm add sqlalchemy-crud-plus
     ```
+
+=== "uv"
+
+    ```sh
+    uv add sqlalchemy-crud-plus
+    ```

docs/usage/create_model.md

@@ -8,7 +8,7 @@ async def create_model(
 ) -> Model:
 ````
 
-!!! note "create_model 独特的关键字参数"
+!!! note "create_model <独特>的关键字参数"
 
     除了必须传入 obj schema 外，还可以通过关键字入参，传入非 schema
     参数，比如，对于某些特定场景，其中一个字段并不是通用的，也不需要进行输入控制，只需在写入时赋予指定值，那么你可以使用关键字入参即可
@@ -24,26 +24,7 @@ async def create_model(
     1. 在数据被最终写入前，所有入参（schema 和关键字参数）都会赋值给 SQLAlchemy 模型，即便你传入了非模型数据，
        这也是安全的，因为它不会被模型所引用
 
-## 提交
 
-此方法提供 `commit` 参数，默认值为 False，它既不会执行提交操作，也不包含 `flush` 等行为，要想真正写入到数据库，你可以通过以下几种方案
-
-1. 设置 `commit=True` 手动提交
-
-      ```py hl_lines="2"
-      async def create(self, db: AsyncSession, obj: CreateIns) -> None:
-          await self.create_model(db, obj, commit=True)
-      ```
-
-2. 使用 `begin()` 事务自动提交
-
-      ```py hl_lines="9"
-      --8<-- "docs/ext/async_db_session.py"
-      
-      async def create(self, obj: CreateIns) -> None:
-          async with async_db_session.begin() as db:
-              await self.create_model(db, obj)
-      ```
 
 ## 示例
 

docs/usage/create_models.md

@@ -7,7 +7,7 @@ async def create_models(
 ) -> list[Model]:
 ```
 
-此方法提供 `commit` 参数，详见：[提交](./create_model.md/#_1)
+此方法提供 `commit` 参数，详见：[提交](../advanced/commit.md)
 
 ## 示例