From 8efb55827c5826c32ce5c88aba97da94f2434abd Mon Sep 17 00:00:00 2001 From: MangoFanFanw Date: Mon, 25 May 2026 20:55:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=86=99=E4=B8=80=E7=82=B9=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=92=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.editorconfig | 10 ++++++++++ docs/dev/api-docs/api.md | 36 ++++++++++++++++++++++++++++++++++++ docs/dev/backend_response.md | 1 + docs/dev/email_templates.md | 19 +++++++++++++++++++ docs/dev/start.md | 3 +++ docs/use/start.md | 11 +++++++++++ 6 files changed, 80 insertions(+) create mode 100644 docs/.editorconfig create mode 100644 docs/dev/api-docs/api.md create mode 100644 docs/dev/backend_response.md create mode 100644 docs/dev/start.md diff --git a/docs/.editorconfig b/docs/.editorconfig new file mode 100644 index 0000000..5129f50 --- /dev/null +++ b/docs/.editorconfig @@ -0,0 +1,10 @@ +[*] +insert_final_newline = true + +[*.{js,ts,mjs,mts}] +indent_style = space +indent_size = 2 + +[*.md] +indent_style = space +indent_size = 2 diff --git a/docs/dev/api-docs/api.md b/docs/dev/api-docs/api.md new file mode 100644 index 0000000..8b15f0d --- /dev/null +++ b/docs/dev/api-docs/api.md @@ -0,0 +1,36 @@ +# API + +以下是自动生成的 API 文档，包含 NyaHome 的 FastAPI 后端拥有的所有路由端点的有关信息。 + +API 文档会跟随代码仓库主分支的最新状况进行同步。也就是说，此处的 API 文档永远显示最新版本。 + +## 查看 NyaHome Swagger UI 或 ReDoc + +FastAPI 提供内置的文档功能，位于开发服务器的 `/docs` 和 `/redoc` 两处路径。 +NyaHome 提供关闭它们的选项（并且默认关闭），但如果你有开发需求，打开它们自然是比较方便的。 + +由 FastAPI 打开的文档是由当前代码生成的，可以反应开发中的最新更改，或者查看当前版本的路由信息（如果你没有使用最新版本）。 + +## 导出 openapi.json + +你可以从一个部署完成的 NyaHome 实例中导出 openapi.json。 + +```bash +uv run nyahome openapi [path] +``` + +以上命令会生成 openapi.json 文件。`path` 参数的默认值是 `openapi.json`，意味着 openapi.json 会被保存在执行位置（仓库根目录）。 + +你也可以从一个正在运行的 NyaHome 实例访问 `/openapi.json` 来在线查看 openapi.json，此功能也默认关闭。 + +## 构建文档自动集成 + +`pyproject.toml` 中配置了一个项目任务，来方便将最新的 openapi.json 导出到 `/docs` 路径下的指定位置，从而与 VitePress 进行集成。 + +```bash +uv run task openapi-docs +``` + +这会将 openapi.json 保存到 `/docs/.vitepress/theme/openapi.json`。事实上这是对上面的 `nyahome openapi` 命令的封装。 + +此命令一般适合在 CI/CD 流水线中运行比较合适，或者在开发阶段需要预览 API 文档的渲染效果。 diff --git a/docs/dev/backend_response.md b/docs/dev/backend_response.md new file mode 100644 index 0000000..858a906 --- /dev/null +++ b/docs/dev/backend_response.md @@ -0,0 +1 @@ +# 后端响应 diff --git a/docs/dev/email_templates.md b/docs/dev/email_templates.md index e9de47f..558fb0a 100644 --- a/docs/dev/email_templates.md +++ b/docs/dev/email_templates.md @@ -13,6 +13,8 @@ HTML。 pnpm mjml mjml/filename.mjml -o public/templates/filename.j2 ``` +NyaHome 的开发状况稳定之后，可能会再优化邮件模板的编译流程。 + Jinja2 在 NyaHome 进程中读取模板，渲染变量，然后由 aiosmptplib 发送渲染好的 HTML 邮件。 ## 在 PyCharm 中预览 mjml 源文件 @@ -22,4 +24,21 @@ Jinja2 在 NyaHome 进程中读取模板，渲染变量，然后由 aiosmptplib :::warning MJML Support 插件不支持 JetBrains 远程开发。在远程开发（包括使用 Gateway 进行 WSL 开发）中，IDE client 无法对 mjml 源文件进行实时预览。 + +MJML Support 的开发者表示该插件不会支持远程开发。 ::: + +## 渲染变量 + +Jinja2 负责将需要动态渲染的变量渲染到经过变异的 Jinja2 模板中。如果你碰过 Django 或者 Flask，应该会对这种格式很熟悉。 + +```html + + +
{{ site_name }} 的管理员选择向此邮箱发送了一封测试邮件。此邮件不含有任何有效内容。
+ + +``` + +本文档不过多设计 Jinja2 的模板变量写法。只需要知道，这些变量会在发送前被填入具体的内容。例如，{{ site_name }} +会被渲染成 `config_manager.get("site_name", "Nya Home")`。 diff --git a/docs/dev/start.md b/docs/dev/start.md new file mode 100644 index 0000000..af1c697 --- /dev/null +++ b/docs/dev/start.md @@ -0,0 +1,3 @@ +# 开始 + +## 从代码仓库克隆项目 diff --git a/docs/use/start.md b/docs/use/start.md index e69de29..e738243 100644 --- a/docs/use/start.md +++ b/docs/use/start.md @@ -0,0 +1,11 @@ +# 开始 + +## 从 uv 安装 + +NyaHome 作为一个 Python 模块发布在了 pypi 上，因此可以使用 uv 将 NyaHome 作为工具安装，然后随处运行。 + +你需要选定一个合适的目录，并在每次都从此处运行 NyaHome。NyaHome 需要在一个指定目录存放数据文件。 + +```bash +uv tool install nyahome +```