Docs: NoneBot2文档改进计划

[mnixry]

NoneBot2文档改进计划

Related: #3 #372

描述问题或主题

NoneBot2文档由于一些原因主要是我们语文太菜，它的撰写方法存在各种问题，对新手的理解和使用造成了困难。
我们在这里希望对NoneBot现有的文档结构作出一点改进。

但是这不是我们几位开发者能够完成的。
我们都是普通人，在完成学习和工作之余维护项目代码和文档，实在感觉有些分身乏术。

我们衷心希望，看到这个issue的每一个人，都为这个文档，作出一份自己的贡献。
而一份好的文档，需要你们每个人的帮助。

不太正经的话

• 我写这么多，要是没人来做我好尴尬啊……
• 
• 来贡献文档，领NoneBot周边这个我得问问RC……也没决定要做啥

需作出的修改

我在这里提供一个列表，包含了我个人在阅读文档过程中发现的一些问题
大家可以在Issue下方补充自己的见解，我会加到下面的这个列表中
如果各位看到这里面的一些问题自己有能力解决，可以向我们提交PR进行修改。

• 更新文档中的所有asciinema示例
• 在文档开篇介绍NoneBot的组成部分（Adapter，Driver，Plugin...）
  • 这部分不用特别详细，因为进阶会详细讲事件处理流程这里
• 在安装方式一节给出最推荐的一种
  • 添加一个使用Conda作为虚拟环境管理工具使用nb-cli的教程
    • 因为它在各种平台上算是比较好装的，也比较适合nb-cli的操作需要
  • 是不是应该把给只使用插件的用户的教程放在这里？
• 把使用脚手架移到教程一节，将教程以脚手架创建的项目结构为核心展开
  • 引导式教程，分步骤，第一步创建项目，第二部选择驱动器/注册适配器 这样的
  • 创建插件一步从脚手架命令开始，讲解创建插件的文件结构，引入Python包的概念
  • 简化加载插件一节，将各种加载插件方式移动到API参考部分
    • 加一条警告，不要随便动bot.py，除非你知道你在干啥
  • 详细化定义插件配置一节，加几个常见字段类型的示例，并且告诉开发者，插件配置应该从哪载入，什么时候实例化
    • 结合脚手架创建的文件结构(config.py)进行讲解
  • 定义事件响应器部分，应该先解释会话的概念
    • 权限控制这里可以直接说，为了可复用的控制一个事件能否被响应，我们提供了两种解决方案，然后打个表格做对比
    • 创建事件响应器，这个地方给例子比较好（比如教用户自己写个echo？），然后具体有哪些扔API文档
  • 定义事件处理流程，把got和receive位置换一下，最好给一个例子做对比
    • 获取上下文信息这一步可以开始提及简单的依赖注入了，给个例子，说明一些依赖是怎样声明的
      • 具体有哪些依赖就不用报菜名了，直接扔API文档链接
  • 删除事件响应器操作一节，补全API相关部分，直接扔链接
  • 优化插件示例一节，按照上面的步骤，构建一个插件应该被打散成了很多步，这里需要给所有文件做个总结，然后可以提一些高阶的东西
  • 移动自定义日志一节到进阶，因为开发入门似乎用不到
• 将钩子函数一节和进阶首页工作原理篇合并，在讲解工作原理的时候标示出各个钩子的运行时机，给个API文档链接即可
• 跨插件访问，加上直接import这一种方法，讲明什么时候该require，什么时候直接import就行
• 权限控制，这个地方想要表达的本质就是PERMISSION是一个(bot,event)->Awaitable[bool]，可以改一下表述方式
• 移动发布插件到进阶最后，让用户在发布插件前就对NoneBot有一个完整的了解
• 删除定时任务的从NoneBot v1迁移一节
  • 尝试修改scheduler插件为可以直接import的版本
• 添加可执行示例

如果对以上部分有任何疑问，也可以在官方交流群里面直接联系我们

---

最后，在这里感谢你们对NoneBot社区作出的贡献！

[yanyongyu]

• dotenv以及环境变量配置的地方需要明确配置项的存在条件，需要dotenv文件中存在的配置项才会从环境变量读取 (Bug: 无法从环境变量中读取列表型变量 #1575 )