# .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、属性索引、工具函数