Add mkdocs usage documentation (#12)

* Add mkdocs usage documentation

* Add basic documents

* Update basic documents

* Improve the documentation of the use

Author: wu-clan

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: docs
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.10
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

README.md

@@ -8,29 +8,9 @@ Asynchronous CRUD operations based on SQLAlChemy 2.0
 pip install sqlalchemy-crud-plus
 ```
 
-## Use
+## 文档
 
-```python
-# example:
-from sqlalchemy.orm import declarative_base
-from sqlalchemy_crud_plus import CRUDPlus
-
-Base = declarative_base()
-
-
-class ModelIns(Base):
-    # your sqlalchemy model
-    pass
-
-
-class CRUDIns(CRUDPlus[ModelIns]):
-    # your controller service
-    pass
-
-
-# singleton
-ins_dao: CRUDIns = CRUDIns(ModelIns)
-```
+[SQLAlchemy CRUD Plus](https://fastapi-practices.github.io/sqlalchemy-crud-plus)
 
 ## 互动
 

docs/advanced/filter.md

@@ -0,0 +1,127 @@
+SQLAlchemy CRUD Plus 支持高级过滤选项，允许使用运算符查询记录，如大于（`__gt`）、小于（`__lt`）；
+
+大多数过滤器操作符需要一个字符串或整数值
+
+```python
+# 获取年龄大于 30 岁以上的员工
+items = await item_crud.select_models(
+    session=db,
+    age__gt=30,
+)
+```
+
+## 比较运算符
+
+- `__gt`：大于
+- `__lt`：小于
+- `__ge`：大于或等于
+- `__le`：小于或等于
+- `__eq`: 等于
+- `__ne`: 不等于
+- `__between`: 在两者之间
+
+## IN 比较
+
+- `__in`: 包含
+- `__not_in`: 不包括
+
+## 身份比较
+
+- `__is`：用于测试 “真”、“假” 和 “无”。
+- `__is_not`：“is” 的否定
+- `__is_distinct_from`: 产生 SQL IS DISTINCT FROM
+- `__is_not_distinct_from`: Produces SQL IS NOT DISTINCT FROM
+- `__like`：针对特定文本模式的 SQL “like” 搜索
+- `__not_like`：“like” 的否定
+- `__ilike`：大小写不敏感的 “like”
+- `__not_ilike`：大小写不敏感的 “not_like”
+
+## 字符串比较
+
+- `__startswith`：文本以给定的字符串开始
+- `__endswith`：文本以给定字符串结束
+- `__contains`：文本包含给定字符串
+
+## 字符串匹配
+
+- `__match`：特定于数据库的匹配表达式
+
+## 字符串修改
+
+- `__concat`: 字符串连接
+
+## 算术运算符
+
+此过滤器使用方法需查看：[算数](#_8)
+
+- `__add`: Python `+` 运算符
+- `__radd`: Python `+` 反向运算
+- `__sub`: Python `-` 运算符
+- `__rsub`: Python `-` 反向运算
+- `__mul`: Python `*` 运算符
+- `__rmul`: Python `*` 反向运算
+- `__truediv`: Python `/` 运算符，这是 Python 的 truediv 操作符，它将确保发生整数真除法
+- `__rtruediv`: Python `/` 反向运算
+- `__floordiv`: Python `//` operator，这是 Python 的 floordiv 运算符，它将确保发生底除
+- `__rfloordiv`: Python `//` 反向运算
+- `__mod`: Python `%` 运算符
+- `__rmod`: Python `%` 反向运算
+
+## BETWEEN、IN、NOT IN
+
+!!! note
+
+    运算符需要多个值，且仅允许元组，列表，集合
+
+```python
+# 获取年龄在 30 - 40 岁之间的员工
+items = await item_crud.select_models(
+    session=db,
+    age__between=[30, 40],
+)
+```
+
+## AND
+
+可以通过将多个过滤器链接在一起来实现 AND 子句
+
+```python
+# 获取年龄在 30 以上，薪资大于 2w 的员工
+items = await item_crud.select_models(
+    session=db,
+    age__gt=30,
+    payroll__gt=20000,
+)
+```
+
+## OR
+
+!!! note
+
+    每个键都应是库已支持的过滤器，仅允许字典
+
+```python
+# 获取年龄在 40 岁以上或 30 岁以下的员工
+items = await item_crud.select_models(
+    session=db,
+    age__or={'gt': 40, 'lt': 30},
+)
+```
+
+## 算数
+
+!!! note
+
+    此过滤器必须传递字典，且字典结构必须为 `{'value': xxx, 'condition': {'已支持的过滤器': xxx}}`
+
+    `value`：此值将与列值进行运算
+
+    `condition`：此值将作为运算后的比较值，比较条件取决于使用的过滤器
+
+```python
+# 获取薪资打八折以后仍高于 15000 的员工
+items = await item_crud.select_models(
+    session=db,
+    payroll__mul={'value': 0.8, 'condition': {'gt': 15000}},
+)
+```

docs/advanced/primary_key.md

@@ -0,0 +1,8 @@
+!!! note 主键参数命名
+
+    由于在 python 内部 id 的特殊性，我们设定 pk (参考 Django) 作为模型主键命名，所以在 crud 方法中，任何涉及到主键的地方，入参都为 `pk`
+    
+```py title="e.g." hl_lines="2"
+async def delete(self, db: AsyncSession, primary_key: int) -> int:
+    return self.delete_model(db, pk=primary_key)
+```

docs/changelog.md

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+from sqlalchemy.ext.asyncio import 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)

docs/ext/async_db_session.py

@@ -0,0 +1,98 @@
+---
+
+**Documentation**: <a href="https://fastapi-practices.github.io/sqlalchemy-crud-plus" target="_blank">https://fastapi-practices.github.io/sqlalchemy-crud-plus</a>
+
+**Source Code**: <a href="https://github.com/fastapi-practices/sqlalchemy-crud-plus" target="_blank">https://github.com/fastapi-practices/sqlalchemy-crud-plus</a>
+
+---
+
+## Installing
+
+=== "pip"
+
+    ```sh
+    pip install sqlalchemy-crud-plus
+    ```
+
+=== "pdm"
+
+    ```sh
+    pdm add sqlalchemy-crud-plus
+    ```
+
+## 示例
+
+=== "api.py"
+
+    ```py
+    from typing import Annotated
+    
+    from fastapi import APIRouter
+
+    router = APIRouter()
+
+
+    @router.get('/{pk}', summary="获取实例")
+    async def get_ins(pk: Annotated[int, Path(...)]) -> InsParam:
+        ins = await ins_service.get_ins()
+        return InsParam(ins)
+    ```
+
+=== "model.py"
+
+    ```py
+    from sqlalchemy.orm import declarative_base
+
+    Base = declarative_base()
+    
+    
+    class ModelIns(Base):
+        # sqlalchemy model
+        pass
+    ```
+
+=== "schema.py"
+
+    ```py
+    from pydantic import BaseModel
+
+    
+    class InsParam(BaseModel):
+        # field
+        pass
+    ```
+
+=== ":star: crud.py"
+
+    ```py hl_lines="7"
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from sqlalchemy_crud_plus import CRUDPlus
+    
+    
+    # 在使用 IDE 时，传入类参数，将获得更友好的键入提示
+    class CRUDIns(CRUDPlus[ModelIns]):
+        async def get(self, db: AsyncSession, pk: int) -> ModelIns:
+            return await self.select_model(db, pk)
+
+    ins_dao: CRUDIns = CRUDIns(ModelIns)
+    ```
+
+=== "service.py"
+
+    ```py
+    class InsService:
+        async def get_ins():
+            async with async_db_session(pk: int) as db:
+                ins = ins_dao.get(db, pk)
+
+    ins_service = InsService()
+    ```
+
+## 互动
+
+[WeChat / QQ](https://github.com/wu-clan)
+
+## 赞助
+
+如果此项目能够帮助到你，你可以赞助作者一些咖啡豆表示鼓励：[Sponsor](https://wu-clan.github.io/sponsor/)

docs/index.md

@@ -0,0 +1,20 @@
+## 依赖
+
+在安装 sqlalchemy-crud-plus 之前，请确保您满足以下先决条件：
+
+- **Python:** 版本 3.10 或更高
+- **SQLAlchemy:** sqlalchemy-crud-plus 使用 SQLAlchemy 2.0 进行数据库操作，因此您需要 SQLAlchemy 2.0 或更高版本
+
+## 安装
+
+=== "pip"
+
+    ```sh
+    pip install sqlalchemy-crud-plus
+    ```
+
+=== "pdm"
+
+    ```sh
+    pdm add sqlalchemy-crud-plus
+    ```

docs/installing.md

@@ -0,0 +1,72 @@
+````py
+async def create_model(
+    self,
+    session: AsyncSession,
+    obj: CreateSchema,
+    commit: bool = False,
+    **kwargs
+) -> Model:
+````
+
+!!! note "create_model 独特的关键字参数"
+
+    除了必须传入 obj schema 外，还可以通过关键字入参，传入非 schema
+    参数，比如，对于某些特定场景，其中一个字段并不是通用的，也不需要进行输入控制，只需在写入时赋予指定值，那么你可以使用关键字入参即可
+   
+    e.g.
+   
+    ```PY
+    async def create(self, obj: CreateIns) -> None:
+        async with async_db_session.begin() as db:
+            await self.create_model(db, obj, status=1)  # (1)
+    ```
+   
+    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)
+      ```
+
+## 示例
+
+```py title="create_model" hl_lines="21"
+from pydantic import BaseModel
+
+from sqlalchemy_crud_plus import CRUDPlus
+
+from sqlalchemy import DeclarativeBase as Base
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class ModelIns(Base):
+    # your sqlalchemy model
+    pass
+
+
+class CreateIns(BaseModel):
+    # your pydantic schema
+    pass
+
+
+class CRUDIns(CRUDPlus[ModelIns]):
+    async def create(self, db: AsyncSession, obj: CreateIns) -> ModelIns:
+        return await self.create_model(db, obj)
+```