📝 write start docs

2024-11-24 00:55:07 +08:00 · 2021-12-24 19:02:11 +08:00 · 2021-12-24 19:02:11 +08:00 · 75e2ca77df
commit 75e2ca77df
parent 6ed87f1910
9 changed files with 1496 additions and 1335 deletions
--- a/website/docs/guide/README.md
+++ b/website/docs/guide/README.md
@ -1,12 +1,7 @@
 ---
-sidebar_position: 1
+sidebar_position: 0
 id: index
 slug: /guide
-
-options:
-  menu:
-    weight: 10
-    category: guide
 ---

 # 概览
--- a/website/docs/guide/start/_category_.json
+++ b/website/docs/guide/start/_category_.json
@ -0,0 +1,4 @@
+{
+  "position": 1,
+  "label": "开始"
+}
--- a/website/docs/guide/start/installation.md
+++ b/website/docs/guide/start/installation.md
@ -1,18 +1,17 @@
 ---
-sidebar_position: 2
+sidebar_position: 0
+description: 通过脚手架, PyPI, GitHub 安装 NoneBot

 options:
  menu:
-    weight: 20
+    weight: 10
    category: guide
 ---

-# 安装
-
-## 安装 NoneBot
+# 安装 NoneBot

 :::warning 注意
-请确保你的 Python 版本 >= 3.7。
+请确保你的 Python 版本 >= 3.7.3。
 :::

 :::warning 注意
@ -24,28 +23,20 @@ pip uninstall nonebot

 :::

-### (推荐安装方式)通过脚手架安装
+## 通过脚手架安装 (推荐)

-1. (推荐)使用你喜欢的 Python 环境管理工具(如 `poetry`)创建新的虚拟环境
+1. (可选) 使用你喜欢的 Python 环境管理工具 (如 `poetry`, `venv`, `conda` 等) 创建新的虚拟环境
 2. 使用 `pip` 或 其他包管理工具 安装 `nb-cli`，`nonebot2` 会作为其依赖被一起安装

   ```bash
   pip install nb-cli
   ```

-3. 点个 star 吧
+<!-- asciinema for installation -->

-   nonebot2: [![nonebot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)
+## 不使用脚手架 (纯净安装)

-   nb-cli: [![nb-cli](https://img.shields.io/github/stars/nonebot/nb-cli?style=social)](https://github.com/nonebot/nb-cli)
-
-4. 如果有疑问，可以加群交流(点击链接直达)
-
-   [![QQ Chat](https://img.shields.io/badge/QQ%E7%BE%A4-768887710-orange?style=social)](https://jq.qq.com/?_wv=1027&k=5OFifDh)
-
-   [![Telegram Chat](https://img.shields.io/badge/telegram-cqhttp-blue?style=social)](https://t.me/cqhttp)
-
-### (纯净安装)不使用脚手架
+如果你不想使用脚手架，可以直接安装 `nonebot2`，并自行完成开发配置。

 ```bash
 pip install nonebot2
@ -53,14 +44,17 @@ pip install nonebot2
 poetry add nonebot2
 ```

+## 从 GitHub 安装
+
 如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：

 :::warning 注意
 直接从 Github 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
+
 在任何情况下请不要将其应用于生产环境!
 :::

-```bash
+```bash title="Install From Github"
 # master分支
 poetry add git+https://github.com/nonebot/nonebot2.git#master
 # dev分支
@ -76,7 +70,7 @@ poetry install --no-dev  # 推荐
 pip install .  # 不推荐
 ```

-## 安装适配器
+<!-- ## 安装适配器

 适配器可以通过 `nb-cli` 在创建项目时根据你的选择自动安装，也可以自行使用 `pip` 安装

@ -121,4 +115,4 @@ nb plugin install <plugin-name>

 NoneBot v2 全程使用 `VSCode` 搭配 `Pylance` 的开发环境进行开发，在严格的类型检查下，NoneBot v2 具有完善的类型设计与声明。

-在围绕 NoneBot v2 进行开发时，使用 `VSCode` 搭配 `Pylance` 进行类型检查是非常推荐的。这有利于统一代码风格及避免低级错误的发生。
+在围绕 NoneBot v2 进行开发时，使用 `VSCode` 搭配 `Pylance` 进行类型检查是非常推荐的。这有利于统一代码风格及避免低级错误的发生。 -->
--- a/website/docs/guide/start/nb-cli.md
+++ b/website/docs/guide/start/nb-cli.md
@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+description: 使用 nb-cli 帮助开发
+
+options:
+  menu:
+    weight: 11
+    category: guide
+---
+
+# 使用脚手架
--- a/website/docs/guide/start/problem.md
+++ b/website/docs/guide/start/problem.md
@ -0,0 +1,26 @@
+---
+---
+
+# 遇到问题
+
+如果在安装或者开发过程中遇到了任何问题，可以通过以下方式解决：
+
+1. 点击下方链接前往 GitHub ~~点击 star~~ ，前往 Issues 页面，在 `New Issue` Template 中选择 `Question`
+
+   [![nonebot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)
+
+2. 通过 QQ 群 (点击下方链接直达)
+
+   [![QQ Chat](https://img.shields.io/badge/QQ%E7%BE%A4-768887710-orange?style=social)](https://jq.qq.com/?_wv=1027&k=5OFifDh)
+
+3. 通过 QQ 频道
+
+   前往 QQ 频道搜索 `NoneBot` 点击加入
+
+4. 通过 Telegram 群 (点击下方链接直达)
+
+   [![Telegram Chat](https://img.shields.io/badge/telegram-cqhttp-blue?style=social)](https://t.me/cqhttp)
+
+5. 通过 Discord 服务器 (点击下方链接直达)
+
+   [![Discord Server](https://discordapp.com/api/guilds/847819937858584596/widget.png?style=shield)](https://discord.gg/VKtE6Gdc4h)
--- a/website/sidebars.js
+++ b/website/sidebars.js
@ -14,67 +14,81 @@
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
-  guide: [
+  tutorial: [
    {
-      type: "category",
-      label: "开始",
-      collapsible: false,
-      items: [
-        "guide/index",
-        "guide/installation",
-        "guide/getting-started",
-        "guide/creating-a-project",
-        "guide/basic-configuration",
-      ],
-    },
-    {
-      type: "category",
-      label: "编写插件",
-      collapsible: false,
-      items: [
-        "guide/loading-a-plugin",
-        "guide/creating-a-plugin",
-        "guide/creating-a-matcher",
-        "guide/creating-a-handler",
-        "guide/end-or-start",
-      ],
-    },
-    {
-      type: "category",
-      label: "协议适配",
-      collapsible: false,
-      items: [
-        "guide/cqhttp-guide",
-        "guide/ding-guide",
-        "guide/mirai-guide",
-        "guide/feishu-guide",
-      ],
-    },
-  ],
-  advanced: [
-    {
-      type: "category",
-      label: "进阶",
-      collapsible: false,
-      items: [
-        "advanced/index",
-        "advanced/scheduler",
-        "advanced/permission",
-        "advanced/runtime-hook",
-        "advanced/export-and-require",
-        {
-          type: "category",
-          label: "高级事件处理",
-          items: [{ type: "autogenerated", dirName: "advanced/handler" }],
-        },
-      ],
-    },
-    {
-      type: "category",
-      label: "发布",
-      collapsible: false,
-      items: ["advanced/publish-plugin"],
+      type: "autogenerated",
+      dirName: "guide",
    },
+    // {
+    //   type: "category",
+    //   label: "指南",
+    //   items: [
+    //     {
+    //       type: "category",
+    //       label: "开始",
+    //       collapsible: false,
+    //       items: [
+    //         "guide/index",
+    //         "guide/installation",
+    //         "guide/getting-started",
+    //         "guide/creating-a-project",
+    //         "guide/basic-configuration",
+    //       ],
+    //     },
+    //     {
+    //       type: "category",
+    //       label: "编写插件",
+    //       collapsible: false,
+    //       items: [
+    //         "guide/loading-a-plugin",
+    //         "guide/creating-a-plugin",
+    //         "guide/creating-a-matcher",
+    //         "guide/creating-a-handler",
+    //         "guide/end-or-start",
+    //       ],
+    //     },
+    //     {
+    //       type: "category",
+    //       label: "协议适配",
+    //       collapsible: false,
+    //       items: [
+    //         "guide/cqhttp-guide",
+    //         "guide/ding-guide",
+    //         "guide/mirai-guide",
+    //         "guide/feishu-guide",
+    //       ],
+    //     },
+    //   ],
+    // },
+    // {
+    //   type: "category",
+    //   label: "进阶",
+    //   items: [
+    //     {
+    //       type: "category",
+    //       label: "进阶",
+    //       collapsible: false,
+    //       items: [
+    //         "advanced/index",
+    //         "advanced/scheduler",
+    //         "advanced/permission",
+    //         "advanced/runtime-hook",
+    //         "advanced/export-and-require",
+    //         {
+    //           type: "category",
+    //           label: "高级事件处理",
+    //           items: [{ type: "autogenerated", dirName: "advanced/handler" }],
+    //         },
+    //       ],
+    //     },
+    //     {
+    //       type: "category",
+    //       label: "发布",
+    //       collapsible: false,
+    //       items: ["advanced/publish-plugin"],
+    //     },
+    //   ],
+    // },
  ],
  api: [{ type: "autogenerated", dirName: "api" }],

--- a/website/src/components/Hero.tsx
+++ b/website/src/components/Hero.tsx
@ -24,7 +24,7 @@ export function Hero(): JSX.Element {
            to="/docs/guide"
            className="inline-block bg-hero text-white font-bold rounded-lg px-6 py-3"
          >
-            开始使用
+            开始使用 <FontAwesomeIcon icon={["fas", "chevron-right"]} />
          </Link>
        </div>
      </div>
@ -55,7 +55,7 @@ export function HeroFeature(props: PropsWithChildren<Feature>): JSX.Element {
      <p className="mt-3 mb-3 max-w-md mx-auto text-sm font-medium tracking-wide uppercase opacity-70 md:mt-5 md:max-w-3xl">
        {tagline}
      </p>
-      <h1 className="text-4xl tracking-tight font-light sm:text-5xl md:text-5xl text-hero">
+      <h1 className="font-mono font-light text-4xl tracking-tight sm:text-5xl md:text-5xl text-hero">
        {title}
      </h1>
      <p className="mt-10 mb-6">{description}</p>
--- a/website/src/pages/index.tsx
+++ b/website/src/pages/index.tsx
@ -10,12 +10,12 @@ import type { Feature } from "../components/Hero";
 import styles from "../css/index.module.css";

 export default function Home() {
-  const feature: Feature = {
+  const firstFeature: Feature = {
    title: "Develop",
    tagline: "fast to code",
    description: "仅需两步，即可开始编写你的机器人",
-  };
-  const features: [Feature, Feature] = [
+  } as const;
+  const secondFeatures = [
    {
      title: "Plugin",
      tagline: "build bot with plugins",
@ -26,13 +26,25 @@ export default function Home() {
      tagline: "write once run everywhere",
      description: "支持多种平台，以及多样的事件响应方式",
    },
+  ] as const;
+  const thirdFeatures = [
+    {
+      title: "Async",
+      tagline: "asynchronous first",
+      description: "异步优先式开发，提高运行效率",
+    },
+    {
+      title: "DI",
+      tagline: "bultin dependency injection system",
+      description: "简单清晰的依赖注入系统，内置依赖函数减少用户代码",
+    },
  ];

  return (
    <Layout>
      <Hero />
      <div className="max-w-7xl mx-auto py-16 px-4 text-center md:px-16">
-        <HeroFeature {...feature}>
+        <HeroFeature {...firstFeature}>
          <CodeBlock
            title="Installation"
            className={clsx("inline-block language-bash", styles.homeCodeBlock)}
@ -58,7 +70,7 @@ export default function Home() {
      </div>
      <div className="max-w-7xl mx-auto py-16 px-4 md:grid md:grid-cols-2 md:gap-6 md:px-16">
        <div className="pb-16 text-center md:pb-0">
-          <HeroFeature {...features[0]}>
+          <HeroFeature {...secondFeatures[0]}>
            <CodeBlock
              title
              className={clsx(
@ -80,7 +92,7 @@ export default function Home() {
          </HeroFeature>
        </div>
        <div className="text-center">
-          <HeroFeature {...features[1]}>
+          <HeroFeature {...secondFeatures[1]}>
            <CodeBlock
              title
              className={clsx(
@ -91,12 +103,58 @@ export default function Home() {
              {[
                "import nonebot",
                "# OneBot",
-                "from nonebot.adapters.onebot.v11 import Bot as OneBot",
+                "from nonebot.adapters.onebot.v11 import Adapter as OneBotAdapter",
                "# 钉钉",
-                "from nonebot.adapters.ding import Bot as DingBot",
+                "from nonebot.adapters.ding import Adapter as DingAdapter",
                "driver = nonebot.get_driver()",
-                'driver.register_adapter("onebot", OneBot)',
-                'driver.register_adapter("ding", DingBot)',
+                "driver.register_adapter(OneBotAdapter)",
+                "driver.register_adapter(DingAdapter)",
+              ].join("\n")}
+            </CodeBlock>
+          </HeroFeature>
+        </div>
+      </div>
+      <div className="max-w-7xl mx-auto py-16 px-4 md:grid md:grid-cols-2 md:gap-6 md:px-16">
+        <div className="pb-16 text-center md:pb-0">
+          <HeroFeature {...thirdFeatures[0]}>
+            <CodeBlock
+              title
+              className={clsx(
+                "inline-block language-python",
+                styles.homeCodeBlock
+              )}
+            >
+              {[
+                "from nonebot import on_message",
+                "# 注册一个消息响应器",
+                "matcher = on_message()",
+                "# 注册一个消息处理器",
+                "# 并重复收到的消息",
+                "@matcher.handle()",
+                "async def handler(event: Event) -> None:",
+                "    await matcher.send(event.get_message())",
+              ].join("\n")}
+            </CodeBlock>
+          </HeroFeature>
+        </div>
+        <div className="text-center">
+          <HeroFeature {...thirdFeatures[1]}>
+            <CodeBlock
+              title
+              className={clsx(
+                "inline-block language-python",
+                styles.homeCodeBlock
+              )}
+            >
+              {[
+                "from nonebot import on_command",
+                "# 注册一个命令响应器",
+                'matcher = on_command("help", alias={"帮助"})',
+                "# 注册一个命令处理器",
+                "# 通过依赖注入获得命令名以及参数",
+                "@matcher.handle()",
+                "async def handler(cmd = Command(), arg = CommandArg()) -> None:",
+                "    await matcher.send()",
              ].join("\n")}
            </CodeBlock>
          </HeroFeature>
--- a/yarn.lock
+++ b/yarn.lock