docs(usage): Update according changes

docs/cmdline_tools/import_user.md

@@ -2,21 +2,23 @@
 此工具可以从其他格式的用户数据库读取用户信息保存到PyFSD使用的数据库。  
 ```shell
 $ python -m pyfsd.utils.import_users --help
-Usage: python -m pyfsd.utils.import_users [options] [filename]
-Options:
-  -c, --config-path=  Path to the config file. [default: pyfsd.toml]
-  -f, --format=       Format of the original database file.
-      --help          Display this help and exit.
-      --version       Display Twisted version and exit.
+usage: __main__.py [-h] [-v] [-c CONFIG_PATH] filename {cfcsim,pyfsd,fsd}
 
-This tool can convert users database in other format into PyFSD format.
-Example:
-$ python -m pyfsd.utils.import_users -f cfcsim cert.sqlitedb3
-$ python -m pyfsd.utils.import_users -f fsd -c env_pyfsd.toml cert.txt
+convert users database in other format into PyFSD's format
+
+positional arguments:
+  filename              filename of the original file
+  {cfcsim,pyfsd,fsd}    format of the original file
+
+options:
+  -h, --help            show this help message and exit
+  -v, --verbose         increase output verbosity
+  -c CONFIG_PATH, --config-path CONFIG_PATH
+                        path to the config of PyFSD
 ```
-命令格式: python -m pyfsd.utils.import\_users -f 格式 -c PyFSD配置文件名(默认为pyfsd.toml,可选) 要导入的数据库文件的文件名  
+命令格式: `python -m pyfsd.utils.import_users -c PyFSD配置文件名(默认为pyfsd.toml,可选) 要导入的文件的格式 要导入的文件的文件名`  
 例:  
 ```shell
-$ python -m pyfsd.utils.import_users -f cfcsim cert.sqlitedb3  # 以cfcsim fork fsd格式把cert.sqlitedb3中的数据读出，然后储存到pyfsd.toml配置的PyFSD数据库
-$ python -m pyfsd.utils.import_users -f fsd -c env_pyfsd.toml cert.txt  # 以fsd cert.txt格式把cert.txt中的数据读出，然后储存到env_pyfsd.toml里配置的数据库
+$ python -m pyfsd.utils.import_users cert.sqlitedb3 cfcsim  # 以cfcsim's fsd fork格式把cert.sqlitedb3中的数据读出，然后储存到pyfsd.toml配置的PyFSD数据库
+$ python -m pyfsd.utils.import_users -c env_pyfsd.toml cert.txt fsd  # 以fsd cert.txt格式把cert.txt中的数据读出，然后储存到env_pyfsd.toml里配置的数据库
 ```

docs/configure.md

@@ -1,20 +1,23 @@
 # 配置
 ## 命令行配置
 ```shell
-$ twistd -n pyfsd --help
-Usage: twistd [options] pyfsd [options]
-Options:
-  -c, --config-path=    Path to the config file. [default: pyfsd.toml]
-      --help            Display this help and exit.
-  -l, --disable-loguru  Use default logger instead of loguru.
-      --version         Display Twisted version and exit.
+$ python -m pyfsd --help
+usage: __main__.py [-h] [-c CONFIG_PATH]
+
+options:
+  -h, --help            show this help message and exit
+  -c CONFIG_PATH, --config-path CONFIG_PATH
+                        Path to the config file.
 ```
--c或--config-path: 配置文件的路径。默认为`pyfsd.toml`。  
--l或--disable-logger: 禁用loguru，使用Twisted默认日志记录器。
+`-c`或`--config-path`: 配置文件的路径。默认为`pyfsd.toml`。  
+`-h`或`--disable-logger`: 打印帮助信息(见上)并退出。
+
 ## 配置文件
 !!! note
 
-    第一次启动会自动生成。无特别声明时，所有配置对都必须存在。
+    目录下没有指定的配置文件时会自动生成。  
+    配置缺失会导致PyFSD报错退出。(见疑难杂症)
+默认配置如下: 
 ```toml
 [pyfsd.database]
 url = "sqlite:///pyfsd.db"
@@ -28,51 +31,137 @@ blacklist = []
 [pyfsd.metar]
 mode = "cron"
 cron_time = 3600
-fetchers = ["NOAA", "anotherfetcher"]
-skip_previous_fetcher = true
+fetchers = ["NOAA"]
+
+[pyfsd.logger.logger]
+handlers = ["default"]
+level = "DEBUG"
+propagate = true
+
+[pyfsd.logger.handlers.default]
+level = "INFO"
+class = "logging.StreamHandler"
+formatter = "colored"
 ```
+接下来分块讲解。
+
 ### 数据库
-通过pyfsd.database表来配置数据库。  
-`url`: 数据库连接描述URL。具体可在[此处](https://docs.sqlalchemy.org/en/13/core/engines.html#database-urls)查看。
+```toml
+[pyfsd.database]
+url = "sqlite:///pyfsd.db"
+```
+通过`pyfsd.database`表来配置数据库。  
+`url`(字符串): 数据库连接描述URL。具体可在[SQLAlchemy文档](https://docs.sqlalchemy.org/en/20/dialects/index.html#included-dialects)查看。
+对于PyFSD来说,这些就够用了:
+```toml
+PostgreSQL: postgresql+asyncpg://user:password@host:port/dbname[?key=value&key=value...]
+MySQL: mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...]
+MariaDB: mariadb+asyncmy://user:password@host:port/dbname[?key=value&key=value...]
+OracleDB: oracle+oracledb://user:password@host:port[/dbname][?service_name=<service>[&key=value&key=value...]]
+MSSQL: mssql+aioodbc://<username>:<password>@<dsnname>[/dbname][?key=value&key=value...]
+SQLite: sqlite+aiosqlite:///file_path
+```
+其中`user`是用户名,`password`是密码,`host`是域名或ip(服务在本机的话一般是`localhost`),`file_path`是到数据库文件的路径,`dbname`是数据库名,[abc]表示abc是可选字段。
+
 ### 客户端
-通过pyfsd.client表来配置客户端协议。  
-`port`: 客户端协议的端口。ECHO Pilot、Swift等连飞软件及原版FSD默认使用6809端口。  
-`motd`: 即Message Of The Day，会在客户端成功登录后发送。  
-`motd_encoding`: MOTD的编码方式。如:`gbk`或`utf-8`。
-`blacklist`: IP黑名单。例：  
 ```toml
 [pyfsd.client]
-(省去一大堆)
-blacklist = ["114.514.191.81", "143.22.124.13"]
+port = 6809
+motd = """Modify motd in pyfsd.toml."""
+motd_encoding = "ascii"
+blacklist = []
 ```
+通过`pyfsd.client`表来配置客户端协议。  
+`port`(整数): 客户端协议的端口。ECHO Pilot、Swift等连飞软件及原版FSD默认使用6809端口。   
+`motd`(字符串): 即Message Of The Day,会在客户端成功登录后发送。如需多行直接在引号内换行即可。  
+`motd_encoding`(字符串): MOTD的编码方式。如:`gbk`或`utf-8`。  
+`blacklist`(字符串列表): IP黑名单。例: `blacklist = ["114.514.191.81", "143.22.124.13"]`  
+
 ### Metar
-通过pyfsd.metar表来配置Metar。  
-`mode`: 下载Metar的模式。可选值:  
-- `cron`: 间隔一段时间下载一次所有机场的Metar，通过`cron_time`配置。  
-此模式下时:  
-`cron_time`: (单位为秒)多久下载一次Metar。  
-- `once`: 每当客户端请求Metar时立即下载相关机场的Metar。  
-`fetchers`: 设置Metar下载器。可以配置多个，一个无法使用时会使用下一个。
-
-`fallback`: 替代计划。  
-解释：当是`cron`模式时，获取一个机场的METAR失败，就会尝试用`once`模式获取。反之亦然，当是`once`模式时，获取一个机场的METAR失败，就会尝试用`cron`模式获取。  
-例:  
 ```toml
 [pyfsd.metar]
 mode = "cron"
 cron_time = 3600
-fetchers = ["NOAA", "xmairavt7"]
-skip_previous_fetcher = false
+fetchers = ["NOAA"]
+fallback_once = false
 ```
-按以上配置，无法在`cron`模式获取到需要的机场的Metar时，就会回退到`once`模式，然后再尝试NOAA源(`once`模式)，如没有获取到再去尝试xmairavt7源。
-做这个模式的初衷是某些METAR源可能缺失某些机场，这个时候就要用其他METAR源去替代。但是从上例可以看出，如果缺失机场的METAR源同时也支持`once`模式，就会浪费时间再去缺失那个机场的METAR源查询。所以：  
-`skip_previous_fetcher`: (bool, true真false假，仅在`cron`模式时生效)跳过`cron`模式时下载时(即缺失那个机场的METAR源)使用的METAR源。`fallback`配置对存在时并且`mode`为`cron`时此配置对也必须存在。如果你不需要此特性，填false。
-例:  
+通过`pyfsd.metar`表来配置Metar。  
+`mode`(字符串): 下载Metar的模式。可选值:  
+
+- `cron`: 间隔一段时间下载一次所有机场的Metar,通过`cron_time`配置。  
+
+在此模式下时还需配置:  
+`cron_time`(数字,单位为秒): 多久下载一次Metar。  
+
+- `once`: 当客户端请求Metar时再下载相关机场的Metar。  
+
+`fetchers`(字符串列表): 设置Metar下载器。可以配置多个,一个无法使用时会使用下一个。  
+`fallback_once`(布尔值): 在`cron`模式获取指定机场无结果后是否尝试用`once`模式获取。  
+
+### 日志
+以下是默认日志配置:   
 ```toml
-[pyfsd.metar]
-mode = "cron"
-cron_time = 3600
-fetchers = ["NOAA", "xmairavt7"]
-skip_previous_fetcher = true
+[pyfsd.logger.logger]
+handlers = ["default"]
+level = "DEBUG"
+propagate = true
+
+[pyfsd.logger.handlers.default]
+level = "INFO"
+class = "logging.StreamHandler"
+formatter = "colored"
+```
+通过`pyfsd.logger`表来配置日志,接下来分块讲解。
+!!! note
+
+    此节配置需要一定Python `logging`基础。如果您没有或读不懂,可以直接跳到配置模板一节。
+
+#### 日志处理器
+```toml
+[pyfsd.logger.handlers.处理器id]
+level = "INFO"
+class = "logging.StreamHandler"
+formatter = "colored"
+```
+通过`pyfsd.logger.handlers.处理器id`表来配置一个日志处理器,可以配置多个,但处理器id不能重复。  
+`level`, `class`等配置详见Python [`logging.config`文档 字典架构细节](https://docs.python.org/zh-cn/3/library/logging.config.html#dictionary-schema-details)的`handlers`小节。  
+`formatter`(字符串): 此日志处理器的格式化器。 选项:  
+
+- `plain`: 无颜色文本日志,适用于日志文件
+- `colored`: 有颜色文本日志,适用于终端输出
+- `json`: JSON格式日志,适用于日志分析
+
+#### 日志记录器
+```toml
+[pyfsd.logger.logger]
+handlers = ["default"]
+level = "DEBUG"
+propagate = true
+```
+通过`pyfsd.logger.logger`表配置日志处理器。以下配置详见Python [`logging.config`文档 字典架构细节](https://docs.python.org/zh-cn/3/library/logging.config.html#dictionary-schema-details)的`loggers`小节。简略概括:   
+`level`(字符串,可选): 全局日志等级。  
+`propagate`(布尔值,可选): 是否把事件传递给更高级的日志记录器。  
+`handlers`(字符串列表,可选): 启用的日志处理器的id的列表,必须是在`pyfsd.logger.handlers`表中配置的。  
+`filters`(字符串列表,可选): 启用的过滤器id的列表。  
+
+#### 日志时间设置(可选)
+```toml
+[pyfsd.logger.time]
+fmt = "timestamp"
+utc = true
+key = "timestamp"
+```
+通过`pyfsd.logger.time`表配置日志的时间设置。  
+`fmt`(字符串): 格式化后时间的格式,可以是`strftime`格式字符串,也可以是`iso`(ISO定义的时间格式),`timestamp`(时间戳)。  
+`utc`(布尔值): 是否按UTC时区来,否则使用系统时区(`fmt`为`timestamp`时`utc`必须为`true`)。  
+`key`(字符串): 日志数组中时间的键名,用`timestamp`就好  
+
+#### 日志杂项(可选)
+```toml
+[pyfsd.logger]
+include_extra = true
+extract_record = true
 ```
-按以上配置，无法在`cron`模式获取到需要的机场的Metar时，就会回退到`once`模式，然后直接尝试xmairavt7源(既跳过NOAA源)。
+通过`pyfsd.logger`配置日志杂项。  
+`include_extra`(布尔值,可选): 是否把日志的`extra`部分输出。  
+`extract_record`(布尔值,可选): 是否把发出日志的线程、进程名输出。  

docs/install.md

@@ -2,21 +2,26 @@
 
 一般地，您可以直接使用pip安装:
 ```
-pip install pyfsd
+pip install pyfsd[数据库]
 ```
-但PyPI上的PyFSD通常不是最新的开发版。建议从[GitHub Actions](https://github.com/gamecss/pyfsd/actions/workflows/python.yml)的Artifacts下载dict，解压后使用pip安装wheel文件即可。  
+其中数据库字段可以是`sqlite3`，`postgresql`，`mysql`，`oracle`，`mssql`中的一种。例如:
+```
+pip install pyfsd[sqlite3]  # SQLite 3
+pip install pyfsd[postgresql]  # PostgreSQL
+pip install pyfsd[mysql]  # MySQL / MariaDB
+pip install pyfsd[oracle]  # OracleDB
+pip install pyfsd[mssql]  # Microsoft SQL Server
+```
+但PyPI上的PyFSD通常不是最新的开发版。建议从[GitHub Actions](https://github.com/cfcsim/pyfsd/actions/workflows/python.yml)的Artifacts下载dict，解压后使用pip安装wheel文件即可。  
 也可以直接安装依赖之后从源代码运行（需要PDM）:
 ```
 pip install pdm # 安装PDM
-pdm install # 安装依赖
+pdm install -G 数据库 # 安装依赖
 eval $(pdm venv activate in-project) # 进入虚拟环境(Linux)
 Invoke-Expression (pdm venv activate in-project) # 进入虚拟环境(Windows)
 ```
-
-## 使用
-
+现在运行PyFSD:  
 ```
-twistd -n pyfsd
+python -m pyfsd
 ```
-如果您不是通过PDM安装启动，您需要使用`PYTHONPATH=. twistd -n pyfsd`来加载插件。  
-（如果没有配置文件存在的话）会自动在当前目录创建配置文件与数据库文件。`
+如果程序没有立即退出，那么安装应该成功了。您现在可以按Ctrl-C退出了。

docs/plugin.md

@@ -1,3 +1,3 @@
 # 插件使用
-一般地，只需要创建pyfsd/plugins目录然后把插件文件丢进去就行。
-以wheel形式安装时需要用`PYTHONPATH=. twistd -n pyfsd`来启动PyFSD，不然不能加载插件。
+在运行PyFSD的目录下创建`pyfsd_plugins`目录(如果没有)然后把插件文件丢进去。
+你应该认真的阅读插件的README文件来知晓配置、冲突、适用PyFSD版本等消息。