跳转至

文档与构建

本文档使用 MkDocs + Material 主题 + i18n 插件构建，源码即 docs/ 目录。

本地预览

pip install mkdocs mkdocs-material "mkdocs-static-i18n"
mkdocs serve        # 默认 http://127.0.0.1:8000，支持热更新

构建静态站点

mkdocs build        # 输出到 site/；--strict 可在断链 / 缺失翻译时报错

目录约定

docs/
├── zh/             # 中文（默认语言）
└── en/             # 英文
    每个语言目录下结构相同：index.md、about.md、guide/、dev/、api/
  • 新增页面：在 zh/ 与 en/ 同步添加同名文件，并在 mkdocs.yml 的 nav 中登记。
  • 导航中文 → 英文的翻译在 nav_translations 中维护。

代码规范（贡献者参考）

  • 文件名：UI 功能页用中文拼音（如 qiudao.py = 求导）；core/、functions/ 等库模块用英文。
  • 分层：计算逻辑放 functions/（纯函数，禁依赖 Qt）；界面放 ui/；公共服务放 core/。
  • 文档字符串：公共函数 / 类应有 docstring，便于生成 API 参考。
  • 懒加载：新增 UI 模块必须登记到 ui/__init__.py 的 _submodules，享受启动加速。

文档分类

本帮助文档分为三大类，便于不同读者快速定位：

  • 用户文档（guide/）：面向使用者，介绍安装、配置与各项功能用法。
  • 开发者文档（dev/）：面向贡献者，介绍架构、如何新增功能、国际化与文档构建。
  • API 参考（api/）：面向二次开发者，列出 core/ 与 functions/ 各模块的对外函数。

贡献流程

  1. Fork 仓库并新建分支。
  2. 在 docs/zh 与 docs/en 同步更新文档。
  3. 本地执行 mkdocs build --strict 确认无断链 / 缺失翻译。
  4. 提交 Pull Request。