docs: update readthedocs

docs/intro/examples.md

@@ -30,35 +30,54 @@
 根据 `DemoSpider` 中的各个 `spider` 对一些应用场景进行简要的补充介绍，总体的介绍为：
 
 ```diff
++ 0).以下场景全支持从 nacos 或 consul 中获取配置，不一一举例。
+
 # 数据存入 Mysql 的场景：
-+ 1).demo_one: 根据本地 VIT 中的 .conf 取 mysql 配置
-+ 3).demo_three: 根据 consul 中取 mysql 配置
-+ 21).demo_mysql_nacos: 根据 nacos 中取 mysql 配置(其它从 nacos 中获取配置的场景不再举例)
-+ 5).demo_five: 异步存入 Mysql 的场景
++ 1).demo_one: 从 .conf 中获取 mysql 配置
++ 3).demo_three: 从 consul 中获取 mysql 配置
++ 21).demo_mysql_nacos: 从 nacos 中获取 mysql 配置
++ 5).demo_five: Twisted 异步存储示例
++ 24).demo_aiomysql: 结合 aiomysql 实现的 asyncio 异步存储示例
++ 13).demo_AyuTurboMysqlPipeline: mysql 同步连接池的示例
 
 # 数据存入 MongoDB 的场景：
-+ 2).demo_two: 根据本地 VIT 中的 .conf 取 mongodb 配置
-+ 4).demo_four: 根据 consul 中取 mongodb 配置
-+ 6).demo_six: 异步存入 MongoDB 的场景
++ 2).demo_two: 从 .conf 中获取 mongodb 配置
++ 4).demo_four: 从 consul 中获取 mongodb 配置
++ 6).demo_six: Twisted 异步存储示例
++ 17).demo_mongo_async: 结合 motor 实现的 asyncio 异步存储示例
+
+# 数据存入 PostgreSQL 的场景(需要安装 ayugespidertools[database])
++ 22).demo_nine: 从 .conf 中获取 postgresql 配置
++ 23).demo_ten: Twisted 异步存储示例
++ 27).demo_eleven: asyncio 异步存储示例
+
+# 数据存入 ElasticSearch 的场景(需要安装 ayugespidertools[database])
++ 28).demo_es: 普通同步存储示例
++ 29).demo_es_async: asyncio 异步存储示例
 
-- 7).demo_seven: 使用 requests 来请求的场景(已删除此功能，更推荐使用 aiohttp 方式)
+# 数据存入 Oracle 的场景(需要安装 ayugespidertools[database])
++ 25). demo_oracle: 普通同步存储示例
++ 26). demo_oracle_twisted: Twisted 异步存储示例
+
+- 7).demo_seven: 使用 requests 来请求的场景(已删除，更推荐 aiohttp 方式)
 + 8).demo_eight: 同时存入 Mysql 和 MongoDB 的场景
 + 9).demo_aiohttp_example: 使用 aiohttp 来请求的场景
 + 10).demo_aiohttp_test: scrapy aiohttp 在具体项目中的使用方法示例
 
 + 11).demo_proxy_one: 快代理动态隧道代理示例
 + 12).demo_proxy_two: 测试快代理独享代理
-+13).demo_AyuTurboMysqlPipeline: mysql 同步连接池的示例
-+14).demo_crawl: 支持 scrapy CrawlSpider 的示例
++ 14).demo_crawl: 支持 scrapy CrawlSpider 的示例
 
 # 本库中给出支持 Item Loaders 特性的示例
-+15).demo_item_loader: 本库中使用 Item Loaders 的示例
--16).demo_item_loader_two: 已删除，可查看上个 demo_item_loader，目前已经可以很方便的使用 Item Loaders 功能了
-
-+17).demo_mongo_async: asyncio 版本存储 mongoDB 的 pipelines 示例
-+18).demo_mq: 数据存入 rabbitmq 的模板示例
-+19).demo_kafka: 数据存入 kafka 的模板示例
-+20).demo_file: 下载图片等文件到本地的模板示例
++ 15).demo_item_loader: 本库中使用 Item Loaders 的示例
+- 16).demo_item_loader_two: 已删除，可查看 demo_item_loader，可方便的使用 Item Loaders 了
+
++ 18).demo_mq: 数据存入 rabbitmq 的模板示例
++ 19).demo_kafka: 数据存入 kafka 的模板示例
++ 20).demo_file: 使用本库 pipeline 下载图片等文件到本地的示例
++ 30).demo_file_sec: 自行实现的图片下载示例
++ 31).demo_oss: 使用本库 pipeline 上传到 oss 的示例
++ 32).demo_oss_sec: 自行实现的 oss 上传示例
 ```
 
 基本查看以上 `spider` 即可了解使用方法，但有些示例还是不够详细，对以上内容进行补充。

docs/intro/tutorial.md

@@ -23,11 +23,13 @@ ayuge startproject DemoSpider
 
 这将创建一个 `DemoSpider` 包含以下内容的目录：
 
+通常情况下，我们只需关心 `spider` 的编写和 `VIT` 中 `.conf` 的配置即可。
+
 ```ini
 DemoSpider/
 |-- DemoSpider			# project's Python module, you'll import your code from here
 |   |-- __init__.py
-|   |-- items.py		# project items definition file, 数据库表枚举信息示例也迁移至此
+|   |-- items.py		# project items definition file
 |   |-- logs			# 日志管理文件夹，可以自定义规则
 |   |   |-- DemoSpider.log	# scrapy 输出日志，文件名称为项目名
 |   |   |-- error.log		# loguru 日志 error 规则输出文件
@@ -48,7 +50,7 @@ DemoSpider/
 
 ## 我们的第一个 Spider
 
-这是我们第一个 `Spider` 的代码。`demo_one.py`将其保存在项目目录下命名的文件 `DemoSpider/spiders`中：
+这是我们第一个 `Spider` 的代码。`demo_one.py` 将其保存在项目目录下命名的文件 `DemoSpider/spiders`中：
 
 ```python
 import json

docs/topics/configuration.md

@@ -16,9 +16,9 @@
 
 [nacos](https://nacos.io) 可用于远程配置管理服务，可以更敏捷和容易地管理微服务平台。
 
-| 参数名 | 参数备注                       | 描述                                                         |
-| ------ | ------------------------------ | ------------------------------------------------------------ |
-| url    | _                              | nacos 配置对应的链接，若有鉴权参数请在 url 中构建。          |
+| 参数名 | 参数备注                       | 描述                                                                                                    |
+| ------ | ------------------------------ |-------------------------------------------------------------------------------------------------------|
+| url    | _                              | nacos 服务对应的链接，若有鉴权参数请在 url 中构建。                                                                       |
 | format | Literal["json", "xml", "yaml"] | nacos url 配置中对应的格式解析方法，支持 json，xml，yaml 解析。请优先使用 json 和 xml 来解析，yaml 解析需要安装 ayugespidertools[all] 依赖。 |
 
 ## [consul]
@@ -27,11 +27,11 @@
 
 不同的是配置中的鉴权 `token` 参数独立了出来。
 
-| 参数名 | 参数备注                              | 描述                                                         |
-| ------ | ------------------------------------- | ------------------------------------------------------------ |
-| url    | _                                     | consul 配置对应的链接，若有鉴权参数请在 url 中构建。         |
+| 参数名 | 参数备注                              | 描述                                           |
+| ------ | ------------------------------------- |----------------------------------------------|
+| url    | _                                     | consul 服务对应的链接。                              |
 | format | Literal["json", "xml", "yaml", "hcl"] | consul url 配置中对应的格式解析方法，支持 json，xml，yaml 解析。 |
-| token  | 可选，默认空                          | consul token 参数。                                          |
+| token  | 可选，默认空                          | consul token 参数。                             |
 
 ## [mysql]
 
@@ -166,14 +166,15 @@
 
 上传到阿里云 oss 的配置参数。
 
-| 参数名               | 参数备注 | 描述                                                         |
-| -------------------- | -------- | ------------------------------------------------------------ |
-| access_key           | _        | 阿里云 access_key_id                                         |
-| access_secret        | _        | 阿里云账号对应的 access_key_secret                           |
-| endpoint             | _        | 填写 Bucket 所在地域对应的 Endpoint                          |
-| bucket               | -        | Bucket                                                       |
-| doc                  | -        | 需要操作的文件夹目录，比如 file/img，为可选参数。            |
-| upload_fields_suffix | 规则字段 | 上传到 oss 的字段规则，包含 upload_fields_suffix 后缀的字段会上传到 oss。 |
-| oss_fields_prefix    | 规则字段 | 上传到 oss 的字段生成的新字段规则，会在原字段添加 oss_fields_prefix 前缀。 |
+| 参数名                   | 参数备注              | 描述                                                |
+|-----------------------|-------------------|---------------------------------------------------|
+| access_key            | _                 | 阿里云 access_key_id                                 |
+| access_secret         | _                 | 阿里云账号对应的 access_key_secret                        |
+| endpoint              | _                 | 填写 Bucket 所在地域对应的 Endpoint                        |
+| bucket                | -                 | Bucket                                            |
+| doc                   | -                 | 需要操作的文件夹目录，比如 file/img，为可选参数。                     |
+| upload_fields_suffix  | 规则字段              | 上传到 oss 的字段规则，包含 upload_fields_suffix 后缀的字段会上传到 oss。 |
+| oss_fields_prefix     | 规则字段              | 上传到 oss 的字段生成的新字段规则，会在原字段添加 oss_fields_prefix 前缀。 |
+| full_link_enable      | 是否开启完整链接，默认 false | 为是否保存完整的 oss 文件链接，默认 false。                       |
 
 遵守规则时的 `oss` 上传逻辑时使用，但更推荐自行实现和构建 `AyuItem` 的方式。具体请看 `demo_oss` 和 `demo_oss_sec` 的场景示例。请自行选择可接受的风格。

docs/topics/items.md

@@ -30,8 +30,8 @@
 
     ```
     # `DataItem` 有 `key_value` 和 `notes` 两个参数，`key_value` 为存储的值；
-    # `notes` 在其他(需要字段注释，比如 `Mysql`，`postgresql`)场景中表示为字段注释，在
-    # `ElasticSearch` 中表示 `es document fields`。
+    # `notes` 在 `ElasticSearch` 存储场景中表示 `es document fields`，在其他(需要字段
+    # 注释时，比如 `Mysql`，`postgresql` 存储)场景中表示为字段注释。
 
     # 普通场景
     demo_item = AyuItem(
@@ -48,13 +48,13 @@
   - 无 `notes` 赋值
 
     ```
-    # 即不需要注释，也不是 es 存储场景下，只赋值 key_value 参数
+    # 即不需要字段注释，也不是 es 存储场景下，只赋值 key_value 参数
 
     demo_item = AyuItem(
         article_title=DataItem(_title),
     )
 
-    # 不过，这种不如直接使用 【普通字段】的优雅赋值方式。
+    # 不过，这种写法风格不如直接使用 【普通字段】的优雅赋值方式。
     ```
 
 ## 实现原理
@@ -66,7 +66,7 @@
 ```python
 def parse(self, response):
     # 存储到 Mysql 场景时 Item 构建示例：
-    ArticleMysqlItem = AyuItem(
+    article_mysql_item = AyuItem(
         article_detail_url=article_detail_url,
         article_title=article_title,
         comment_count=comment_count,
@@ -76,14 +76,14 @@ def parse(self, response):
     )
 
     # 存储到 MongoDB 场景时 Item 构建示例：
-    ArticleMongoItem = AyuItem(
+    article_mongo_item = AyuItem(
         article_detail_url=article_detail_url,
         article_title=article_title,
         comment_count=comment_count,
         favor_count=favor_count,
         nick_name=nick_name,
         _table="_article_info_list",
-        # 这里表示以 article_detail_url 为去重规则，若存在则更新，不存在则新增
+        # 可选参数，此示例表示以 article_detail_url 为去重规则，若存在则更新，不存在则新增
         _mongo_update_rule={"article_detail_url": article_detail_url},
     )
 
@@ -107,7 +107,7 @@ def parse(self, response):
 # 如非场景需要，不推荐使用 DataItem 的方式构建 AyuItem，不太优雅。
 ```
 
-以上可知，目前可直接将需要的参数在对应 `Item` 中直接按 `key=value` 赋值即可，`key` 即为存储至库中字段，`value` 为存储内容。
+以上可知，目前可直接将需要的参数在对应 `Item` 中直接按 `key=value` 赋值即可，`key` 为存储至库中字段，`value` 为对应 `key` 所存储的值。
 
 当然，目前也支持动态赋值，但我还是推荐直接创建好 `AyuItem` ，方便管理：