1 unstable release

Uses new Rust 2024

0.1.0	Oct 19, 2025

#216 in Cargo plugins

128 downloads per month

MIT/Apache

205KB
5K SLoC

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/宏/常量/类型/模块）
搜索历史 - 自动保存和恢复搜索历史

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

生成文档 Generate documentation:
```
cargo doc
```
启动运行时服务 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.
可选：静态注入 Optional static enhance:
```
cargo doc-enhance enhance --doc-dir target/doc
```
该模式会直接修改 HTML 文件，并生成 cdv-crate-overview.html 便于离线浏览。

撤销增强 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 服务在“响应阶段”注入增强组件：

请求拦截 - 捕获对 .html 文件的访问，对静态资源直接透传
运行时注入 - 在返回内容前插入 CSS/JS，不对磁盘文件做任何修改
概览页面 - /cdv-crate-overview.html 动态扫描 doc 目录并实时渲染
可选静态模式 - enhance 子命令仍可就地改写 HTML，并写入标记便于 revert
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

Fork 仓库并创建功能分支
确保代码通过 cargo check 和 cargo clippy
测试增强和撤销功能都能正常工作
提交 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 估算及复制上下文的快捷操作。

Dependencies

~7–20MB
~226K SLoC

app cargo-doc-viewer