基于 Sphinx + Furo 的 MatrixOne Intelligence 文档站点,支持中英双语。
当前内容:
- MatrixOne Intelligence - AI 原生多模态数据平台,中文 479 篇全量、英文核心页面覆盖
前置:macOS / Linux,已安装 uv。
uv sync # 装依赖
make html # 构建 MOI 站点到 build/html/
make serve # 构建并启动本地服务 -> http://localhost:8000只构建指定语言:
cd docs && make html # zh + en
cd docs && make html-zh # 只中文
cd docs && make html-en # 只英文清理:
make clean # 删根目录 build/| 路径 | 说明 |
|---|---|
/ |
跳转到 /docs/ |
/docs/ |
按浏览器语言跳到 zh/ 或 en/ |
/docs/zh/ |
MatrixOne Intelligence 中文站 |
/docs/en/ |
MatrixOne Intelligence 英文站 |
_theme/ 放共享主题资源(CSS/JS/模板/Sphinx 配置基类),docs/{zh,en}/ 放 MOI 文档内容。
moi-docs/
├── pyproject.toml
├── Makefile # 根入口:构建 MOI + redirect
├── README.md
│
├── _theme/ # 共享主题
│ ├── conf_base.py # 共享 Sphinx / MyST / Furo 配置基类
│ ├── _static/
│ │ ├── css/custom.css # 站点样式与品牌变量
│ │ ├── js/ # topbar / breadcrumb / lang-switcher / version-switcher / icons / ...
│ │ └── images/ # logo 等资源
│ └── _templates/
│ └── page.html # 覆盖 Furo page.html,给 <html> 注入 data-product
│
├── docs/
│ ├── conf.py # from conf_base import *,声明 MOI 产品维度
│ ├── Makefile
│ ├── zh/ # 中文内容
│ └── en/ # 英文核心页面
│
└── scripts/
├── migrate_intelligence.py # 从 moc-docs 迁移 MOI 内容
├── convert_admonitions.py # MkDocs admonition / tab -> MyST 批量转换
└── translate_batch.py # 批量翻译 zh -> en
- 主题层修改(CSS/JS/模板)集中在
_theme/。 - MOI 品牌色通过
html[data-product="intelligence"]覆写--mo-primary等 token。 docs/conf.py只放产品名、html_context.product、独有 JS 等产品维度配置;Sphinx/MyST/扩展配置集中在_theme/conf_base.py。
产物目录:
build/html/
├── index.html # 跳转到 docs/
└── docs/{index.html,zh/,en/}
| 项 | 选型 |
|---|---|
| 静态站生成 | Sphinx 7.x |
| 内容格式 | Markdown(MyST) |
| 主题 | Furo |
| 扩展 | myst-parser / sphinx-copybutton / sphinx-design |
| 中文分词 | jieba |
| 包管理 | uv |
- 在
docs/<lang>/新建子目录,放入对应语言内容。 - 在
docs/Makefile加html-<lang>目标,把SPHINX_LANG和-D language=传进去。 - 在
_theme/_static/js/lang-switcher.js加新语言的 label 和路径解析规则。
直接在 docs/<lang>/ 下加 .md 文件,并在所属 section 的 index.md 或主索引的 {toctree} 里挂上路径,重新 make html。
_theme/_static/js/lang-switcher.js 顶部的 PARTIAL_EN 控制右上角语言切换 pill。英文站只翻了部分页面时,中文页只有在白名单里才显示切换入口,避免跳到 404。
新翻译一篇文档时,把对应 <rest> 路径加进 PARTIAL_EN['docs']。
当前只有 latest 一个版本。顶部版本切换器是 UI 占位,下拉里只显示 latest 加一段"历史版本归档功能开发中"的提示文字。
未来扩展思路(本仓库不实现):
- 单源构建多个版本 -> 输出到
build/html/docs/<version>/<lang>/ - 历史版本归档目录
archive/docs/<version>/,直接拷成静态产物 - 版本切换器从静态
versions.json读列表
研发上线时再根据真实版本管理需求选定方案。
| 任务 | 命令 |
|---|---|
| 本地预览 | make serve |
| 构建 MOI 全站 | cd docs && make html |
| 构建 MOI 中文 | cd docs && make html-zh |
| 构建 MOI 英文 | cd docs && make html-en |
| 重新跑 MOI 迁移脚本 | uv run python scripts/migrate_intelligence.py |
| 清理 | make clean |
以下文件含 [占位:...] 标记,需要内容团队填写概览文案:
docs/zh/get-started/index.mddocs/zh/overview/index.mddocs/zh/genai-workspace/index.mddocs/zh/database-instance/index.mddocs/zh/develop/index.mddocs/zh/database-instance/reference/index.mddocs/zh/help/index.mddocs/zh/release-notes/index.md
填写要求:
- 长度:1-3 句话,50-100 字
- 内容:说明这章节讲什么、谁适合看、能学到什么
- 避免:不要写成"详见以下内容"这种空话
本项目是演示原型,不是生产文档站。多版本切换、全文搜索后端、CI/CD 等生产能力均未覆盖。