DevDocs — API文档浏览器

DevDocs将多种开发者文档整合到一个干净、有组织的Web界面中，具有即时搜索、离线支持、移动版、深色主题、键盘快捷键等功能。

DevDocs由Thibaut Courouble创建，并由freeCodeCamp运营。

我们目前正在寻找维护者

如果您想加入团队，请通过Discord与社区联系！

关注开发动态：

加入DevDocs的Discord聊天室
在GitHub上关注项目
在Twitter上关注@DevDocs

目录： 快速开始 · 愿景 · 应用 · 抓取器 · 命令 · 贡献 · 文档 · 相关项目 · 许可证 · 问题?

快速开始

除非您想为项目做贡献，否则我们建议使用devdocs.io上的托管版本。它是最新的，并且开箱即用支持离线功能。

DevDocs由两部分组成：一个生成文档和元数据的Ruby抓取器，以及一个由小型Sinatra应用支持的JavaScript应用。

DevDocs需要Ruby 3.3.0（在Gemfile中定义）、libcurl和ExecJS支持的JavaScript运行时（OS X和Windows中包含；Linux上需要Node.js）。安装完这些后，运行以下命令：

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs
gem install bundler
bundle install
bundle exec thor docs:download --default
bundle exec rackup

最后，在浏览器中访问localhost:9292（第一次请求需要几秒钟来编译资源）。一切就绪。

thor docs:download命令用于从DevDocs服务器下载预生成的文档（例如thor docs:download html css）。运行thor docs:list可以查看可用文档和版本列表。要更新所有已下载的文档，运行thor docs:download --installed。要下载并安装本项目提供的所有文档，运行thor docs:download --all。

**注意：**目前没有其他更新机制，只能通过git pull origin main更新代码，通过thor docs:download --installed下载最新版本的文档。要及时了解新版本发布，请确保关注此仓库。

另外，DevDocs也可以作为Docker容器启动：

# 首先，构建镜像
git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs
docker build -t thibaut/devdocs .

# 最后，启动DevDocs容器（访问http://localhost:9292）
docker run --name devdocs -d -p 9292:9292 thibaut/devdocs

愿景

DevDocs旨在使阅读和搜索参考文档变得快速、简单和愉快。

应用的主要目标是：

尽可能缩短加载时间
提高搜索结果的质量、速度和顺序
最大化缓存和其他性能优化的使用
保持清晰易读的用户界面
完全支持离线功能
支持全键盘导航
通过在所有文档中使用一致的排版和设计来减少"上下文切换"
通过专注于特定类别的内容（API/参考）并只索引大多数开发者最有用的最小内容来减少杂乱

**注意：**DevDocs既不是编程指南，也不是搜索引擎。我们所有的内容都来自第三方来源，本项目不打算与全文搜索引擎竞争。它的核心是元数据；每一条内容都由一个唯一的、"显而易见"且简短的字符串标识。不符合这一要求的教程、指南和其他内容都不在项目范围内。

应用

Web应用完全是客户端JavaScript，用CoffeeScript编写，由一个小型的Sinatra/Sprockets应用驱动。它依赖于抓取器生成的文件。

许多代码设计决策都源于应用使用XHR直接将内容加载到主框架的事实。这包括剥离原始文档的大部分HTML标记（如脚本和样式表）以避免污染主框架，以及为所有CSS类名添加下划线前缀以防止冲突。

另一个驱动因素是性能和一切都在浏览器中发生的事实。使用服务工作线程（带有自己的一系列约束）和localStorage来加快启动时间，同时通过允许用户选择自己的文档集来控制内存消耗。搜索算法保持简单，因为即使在搜索100,000个字符串时也需要快速。

作为一个开发者工具，DevDocs的浏览器要求很高：

Firefox、Chrome或Opera的最新版本
Safari 11.1+
Edge 17+
iOS 11.3+

这允许代码利用最新的DOM和HTML5 API，使开发DevDocs变得更加有趣！

抓取器

抓取器负责生成应用使用的文档和索引文件（元数据）。它用Ruby编写，位于Docs模块下。目前有两种抓取器：通过HTTP下载文件的UrlScraper和从本地文件系统读取文件的FileScraper。它们都会复制HTML文档，递归地按照一套规则跟踪链接，并在此过程中进行各种修改，同时还会构建文件及其元数据的索引。文档解析使用Nokogiri。

对每个文档进行的修改包括：

移除内容，如文档结构（<html>、<head>等）、注释、空节点等
修复链接（如删除重复项）
将所有外部（未抓取的）URL替换为其完全限定的对应项
将所有内部（已抓取的）URL替换为其非限定和相对的对应项
添加内容，如标题和原始文档的链接
使用Prism确保正确的语法高亮

这些修改通过使用HTML::Pipeline库的一系列过滤器来应用。每个抓取器包含特定于自身的过滤器，其中一个负责确定页面的元数据。

最终结果是一组标准化的HTML片段和两个JSON文件（索引+离线数据）。由于索引文件是根据用户偏好由应用程序单独加载的，抓取器还会创建一个JSON清单文件，包含系统当前可用文档的信息（如名称、版本、更新日期等）。

docs文件夹中提供了有关抓取器和过滤器的更多信息。

可用命令

命令行界面使用Thor。要查看所有命令和选项，请在项目根目录运行thor list。

# 服务器
rackup              # 启动服务器（按ctrl+c停止）
rackup --help       # 列出服务器选项

# 文档
thor docs:list      # 列出可用文档
thor docs:download  # 下载一个或多个文档
thor docs:manifest  # 创建应用程序使用的清单文件
thor docs:generate  # 生成/抓取一个文档
thor docs:page      # 生成/抓取一个文档页面
thor docs:package   # 打包文档以供docs:download使用
thor docs:clean     # 删除文档包

# 控制台
thor console        # 启动REPL
thor console:docs   # 在"Docs"模块中启动REPL

# 可以在控制台中使用"test"命令快速运行测试。
# 运行"help test"获取使用说明。
thor test:all       # 运行所有测试
thor test:docs      # 运行"Docs"测试
thor test:app       # 运行"App"测试

# 资源
thor assets:compile # 编译资源（开发模式下不需要）
thor assets:clean   # 清理旧资源

如果系统上安装了多个Ruby版本，必须通过bundle exec运行命令。

贡献

欢迎贡献。请阅读贡献指南。

文档

项目	描述	最近提交	星标数
yannickglt/alfred-devdocs	Alfred 工作流
Merith-TK/devdocs_webapp_kotlin	Android 应用
gruehle/dev-docs-viewer	Brackets 扩展
egoist/devdocs-desktop	Electron 应用
skeeto/devdocs-lookup	Emacs 函数
astoff/devdocs.el	Emacs 查看器
naquad/devdocs-shell	GTK shell 与 Vim 集成
hardpixel/devdocs-desktop	GTK 应用
qwfy/doc-browser	Linux 应用
dteoh/devdocs-macos	macOS 应用
Sublime Text 插件	Sublime Text 插件
mohamed3nan/DevDocs-Tab	VS Code 扩展（以标签页形式查看）
deibit/vscode-devdocs	VS Code 扩展（在浏览器中打开）
mdh34/quickDocs	基于 Vala/Python 的查看器
girishji/devdocs.vim	Vim 插件和 TUI（在 Vim 内浏览）
romainl/vim-devdocs	Vim 插件
waiting-for-dev/vim-www	Vim 插件
luckasRanarison/nvim-devdocs	Neovim 插件
toiletbril/dedoc	基于终端的查看器
Raycast Devdocs	Raycast 扩展	不可用	不可用