99 lines
2.7 KiB
Markdown
99 lines
2.7 KiB
Markdown
# .zread — sunvpy 静态文档站点生成器
|
||
|
||
将 `sunvpy` wiki markdown 文档构建为可浏览的静态文档站点。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.zread/
|
||
├── build.py # 构建脚本
|
||
├── wiki/ # 文档源文件
|
||
│ ├── current # 当前版本指针
|
||
│ └── versions/ # 按版本存放 markdown + wiki.json
|
||
└── docs/ # 构建输出（静态站点）
|
||
├── index.html
|
||
├── css/style.css
|
||
├── js/app.js
|
||
├── js/search.js
|
||
├── data/ # nav.json, search-index.json
|
||
└── content/ # markdown 文件副本
|
||
```
|
||
|
||
## 构建文档
|
||
|
||
```bash
|
||
# 默认构建最新版本
|
||
python build.py
|
||
|
||
# 指定版本
|
||
python build.py --version 2026-04-07-163229
|
||
|
||
# 指定输出目录
|
||
python build.py --output /path/to/output
|
||
```
|
||
|
||
构建流程：
|
||
1. 读取 `wiki/versions/<version>/wiki.json` 清单
|
||
2. 生成 `data/nav.json`（侧边栏导航树）
|
||
3. 生成 `data/search-index.json`（全文搜索索引）
|
||
4. 复制 markdown 文件到 `content/`
|
||
|
||
## 查看文档
|
||
|
||
`docs/` 是纯静态站点，用任意 HTTP 服务器托管即可。以下任选一种：
|
||
|
||
### Python
|
||
|
||
```bash
|
||
cd docs
|
||
python -m http.server 8080
|
||
# 访问 http://localhost:8080
|
||
```
|
||
|
||
### Node.js
|
||
|
||
```bash
|
||
npx serve docs -p 8080
|
||
# 访问 http://localhost:8080
|
||
```
|
||
|
||
### VS Code
|
||
|
||
安装 **Live Server** 扩展，右键 `docs/index.html` → "Open with Live Server"。
|
||
|
||
### 直接双击
|
||
|
||
双击 `docs/index.html` 即可在浏览器打开，但搜索和 CDN 资源（代码高亮、Mermaid）需要网络连接。
|
||
|
||
## 站点功能
|
||
|
||
- **侧边栏导航** — 按 section/group 自动组织
|
||
- **全文搜索** — 基于 Fuse.js，支持 `Ctrl+K` 快捷键
|
||
- **深色/浅色主题切换**
|
||
- **代码高亮** — highlight.js（Python）
|
||
- **Mermaid 图表渲染**
|
||
- **页面内目录（TOC）**
|
||
- **移动端响应式布局**
|
||
|
||
## 技术栈
|
||
|
||
| 用途 | 依赖 |
|
||
|------|------|
|
||
| Markdown 渲染 | marked.js (CDN) |
|
||
| 代码高亮 | highlight.js (CDN) |
|
||
| 图表 | mermaid.js (CDN) |
|
||
| 搜索 | fuse.js (CDN) |
|
||
|
||
## 文档内容概览
|
||
|
||
共 45 篇文档，覆盖以下章节：
|
||
|
||
- **快速入门** — 库概述、安装配置、第一个脚本
|
||
- **核心概念与架构** — 系统架构、SWIG 封装、工作空间、Mixin 模式
|
||
- **选择集与查询** — 选择集操作、地物属性读写
|
||
- **地理对象编辑** — 对象创建/删除、批量操作、缓存机制
|
||
- **数据交换与导入导出** — 数据导入导出、自定义流程
|
||
- **数据检查与验证** — 检查记录、自定义规则
|
||
- **高级功能** — 工作空间信息、路径管理、日志、进度条
|
||
- **参考手册** — SSProcessManager API、属性索引、工具函数
|