cargo-doc-viewer 0.1.0

# cargo-doc-viewer

[![Rust](https://img.shields.io/badge/rust-stable-brightgreen.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)

一个增强 Rust 文档浏览体验的工具，为 `cargo doc` 生成的 HTML 文件注入交互式界面组件。通过 `cargo doc-enhance` 子命令即可运行增强版文档服务。

A tool that enhances Rust documentation browsing experience by injecting interactive UI components into HTML files generated by `cargo doc`.

## ✨ 特性 Features

### 🔍 增强搜索 Enhanced Search
- **固定顶部搜索栏** - 保持搜索功能始终可见
- **搜索结果筛选** - 按类型筛选搜索结果（方法/函数/结构体/枚举/Trait/宏/常量/类型/模块）
- **搜索历史** - 自动保存和恢复搜索历史

### 🧭 智能导航 Smart Navigation
- **Home 导航下拉菜单** - 快速返回当前包首页或查看所有包概览
- **函数下拉选择器** - 在顶部快速选择当前页面的函数
- **符号面板** - 按类别组织的页面符号列表
- **键盘导航** - 使用快捷键在标题间导航

### 💬 AI 聊天助手 AI Chat Assistant
- **页面相关问答** - 基于当前文档内容的智能问答
- **文本检索** - 自动从当前页面提取相关内容
- **简洁界面** - 类似 LLM 的聊天界面
- **上下文分层提示** - 自动拼装系统提示、环境信息、页面摘要、选区与历史消息
- **YAML 配置** - 首次运行生成 `~/.cargo-doc-viewer/config.yaml` 模板，可自定义模型、提示词与上下文策略

### 🎨 用户体验改进 UX Improvements
- **专注模式** - 隐藏干扰元素，专注阅读文档
- **代码复制按钮** - 一键复制代码块
- **标题深链接** - 点击复制标题链接，高亮显示
- **滚动位置记忆** - 刷新页面后恢复滚动位置
- **响应式设计** - 适配各种屏幕尺寸
- **离线缓存** - Service Worker 自动缓存页面与静态资源，断网时也能回看

### 🔧 开发者友好 Developer Friendly
- **幂等操作** - 可安全多次运行，自动检测已注入内容
- **轻松撤销** - 使用 `--revert` 参数移除所有注入的增强功能
- **离线工作** - 无需网络连接，所有功能本地运行
- **最小依赖** - 主要使用 Rust 标准库，构建快速可靠

## 🚀 快速开始 Quick Start

### 安装 Installation

```bash
# 克隆仓库
git clone https://github.com/your-username/cargo-doc-viewer.git
cd cargo-doc-viewer

# 构建发布版本
cargo build --release

# 可选：安装到系统路径
cargo install --path .
```

### 基本使用 Basic Usage

1. **生成文档** Generate documentation:
   ```bash
   cargo doc
   ```

2. **启动运行时服务** Start the runtime server (默认行为 Default):
   ```bash
   cargo doc-enhance
   # 自定义监听地址和端口
   cargo doc-enhance serve --addr 127.0.0.1:4200
   ```
   浏览器打开 `http://127.0.0.1:7878/` 即可查看增强后的文档；所有 HTML 在响应阶段注入，无需写回磁盘。
   默认在工程根目录运行时，如果尚未生成文档，工具会自动执行 `cargo doc` 并在完成后启动服务。\
   When invoked from the project root without an explicit `--doc-dir`, the tool now runs `cargo doc` automatically before serving when no documentation is present.

3. **可选：静态注入** Optional static enhance:
   ```bash
   cargo doc-enhance enhance --doc-dir target/doc
   ```
   该模式会直接修改 HTML 文件，并生成 `cdv-crate-overview.html` 便于离线浏览。

4. **撤销增强** Revert enhancements:
   ```bash
   cargo doc-enhance revert --doc-dir target/doc
   ```

### 命令行选项 Command Line Options

```
cargo doc-enhance [serve] [-d|--doc-dir <path>] [--addr <ip:port>] [--port <port>]
cargo doc-enhance enhance [-d|--doc-dir <path>]
cargo doc-enhance revert [-d|--doc-dir <path>]

OPTIONS:
    -d, --doc-dir <path>    指定文档目录 (默认: target/doc)
    --addr <ip:port>        运行时模式监听地址 (默认: 127.0.0.1:7878)
    --port <port>           快速指定端口，等价于 --addr 127.0.0.1:<port>
    -h, --help              显示帮助信息

EXAMPLES:
    cargo doc && cargo doc-enhance          # 启动本地服务
    cargo doc-enhance serve --port 4200     # 指定端口
    cargo doc-enhance enhance --doc-dir target/doc
    cargo doc-enhance revert --doc-dir target/doc
```

## 🛠️ 工作原理 How It Works

默认的 **serve 模式** 通过本地 HTTP 服务在“响应阶段”注入增强组件：

1. **请求拦截** - 捕获对 `.html` 文件的访问，对静态资源直接透传
2. **运行时注入** - 在返回内容前插入 CSS/JS，不对磁盘文件做任何修改
3. **概览页面** - `/cdv-crate-overview.html` 动态扫描 `doc` 目录并实时渲染
4. **可选静态模式** - `enhance` 子命令仍可就地改写 HTML，并写入标记便于 `revert`
5. **Service Worker** - 首次访问后自动注册，缓存 HTML 与静态资源以支持离线浏览

### 架构特点 Architecture Features

- ✅ **非侵入式** - 默认运行时注入，可随时重新生成文档无需二次处理
- ✅ **虚拟概览** - 概览页面按需生成，无需写入额外文件
- ✅ **老模式兼容** - 静态增强与撤销流程保持可用，方便离线分享
- ✅ **自包含资产** - CSS/JS 存放在 `src/assets/`，编译时嵌入二进制

## 🎯 使用场景 Use Cases

### 日常开发 Daily Development
```bash
# 开发工作流
cargo doc && cargo doc-enhance
open target/doc/my_crate/index.html
```

### 文档审查 Documentation Review
```bash
# 为团队审查增强文档体验
cargo doc --document-private-items
cargo doc-enhance --doc-dir target/doc
```

### 演示和教学 Presentations & Teaching
```bash
# 为演示或教学准备增强的文档
cargo doc --examples
cargo doc-enhance
# 使用专注模式进行演示
```

## 🔧 自定义和扩展 Customization & Extension

### URL 参数 URL Parameters

在文档 URL 中添加参数来控制功能：

- `?cdv-notop` - 禁用顶部搜索栏
- `?cdv-nochat` - 禁用 AI 聊天功能
- `?cdv-nosym` - 禁用符号面板

示例：`target/doc/my_crate/index.html?cdv-notop&cdv-nochat`

### 本地存储 Local Storage

工具使用 localStorage 保存用户偏好：

- 搜索历史和筛选设置
- 专注模式状态
- 滚动位置记忆

键名按文档根路径和包名作用域区分。

## 🤝 贡献 Contributing

我们欢迎各种形式的贡献！

### 开发环境设置 Development Setup

```bash
git clone https://github.com/your-username/cargo-doc-viewer.git
cd cargo-doc-viewer

# 运行检查
cargo check

# 测试修改
cargo doc  # 生成测试文档
cargo run --  # 默认启动 serve 模式
# 浏览器访问 http://127.0.0.1:7878 查看效果

# 测试撤销功能
cargo run -- revert
```

### 修改 UI 组件 Modifying UI Components

- **样式修改** - 编辑 `src/assets/cdv.css`
- **功能修改** - 编辑 `src/assets/cdv.js`
- **注入逻辑** - 在 `src/injector.rs` 中调整 Rust 侧的 HTML 处理
- **运行时服务** - 修改 `src/server.rs` 自定义路由或缓存策略

### 提交指南 Contribution Guidelines

1. Fork 仓库并创建功能分支
2. 确保代码通过 `cargo check` 和 `cargo clippy`
3. 测试增强和撤销功能都能正常工作
4. 提交 PR 并描述你的更改

## 📄 许可证 License

本项目采用 MIT 或 Apache-2.0 双重许可证。

This project is licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))

## 🙏 致谢 Acknowledgments

- 感谢 Rust 团队提供出色的 rustdoc 工具
- 感谢所有贡献者和用户的反馈

---

**如果这个工具对你有帮助，请给个 ⭐️ 支持一下！**

**If this tool helps you, please give it a ⭐️!**
### AI Chat 配置 AI Chat Configuration
- 首次打开聊天面板时，会在 `~/.cargo-doc-viewer/config.yaml`（或手动指定的 `CDV_CONFIG_PATH`）创建配置模板。
- 通过 YAML 配置可自定义：
  - `api`：兼容 OpenAI 的接口地址、模型名称、默认请求头与超时时间；
  - `prompts`：系统提示词、环境模板、备选响应语言；
  - `context`：选区去抖时间、页面摘要 Token 预算、历史轮次窗口与敏感信息清洗规则；
  - `ui`：默认语言、是否自动展开上下文预览、是否允许编辑系统提示。
- 配置值支持 `$VAR` / `${VAR}` 引用环境变量；解析顺序为进程环境 → 配置同目录 `.env` → 当前工作目录 `.env` → `$HOME/.env`，便于安全加载 API Key 与自定义 API 基址。
- 前端会自动将 `localStorage` 中的 API Key 与模型覆写应用于请求，并在“Context”面板中展示上下文层级、Token 估算及复制上下文的快捷操作。