cargo-doc-viewer

一个增强 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

# 克隆仓库
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:

   cargo doc
   

2. 启动运行时服务 Start the runtime server (默认行为 Default):

   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:

   cargo doc-enhance enhance --doc-dir target/doc
   

   该模式会直接修改 HTML 文件，并生成 cdv-crate-overview.html 便于离线浏览。

4. 撤销增强 Revert enhancements:

   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

# 开发工作流
cargo doc && cargo doc-enhance
open target/doc/my_crate/index.html

文档审查 Documentation Review

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

演示和教学 Presentations & Teaching

# 为演示或教学准备增强的文档
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

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)
• MIT License (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 估算及复制上下文的快捷操作。