企业官网建设流程全解析

DevDocs 如何为 R 语言文档编译并获取本地 HTML 源文件？

【免费下载链接】devdocsAPI Documentation Browser项目地址: https://gitcode.com/GitHub_Trending/de/devdocs

DevDocs 里的 R 文档和大多数文档不一样：它的 scraperDocs::R继承自FileScraper，不从网上抓取，而是直接读取仓库本地目录docs/r里的文件。如果这个目录不存在，scraping 会直接抛出SetupError。所以要在本地生成 R 文档，必须先自己编译 R 源码、生成静态 HTML 页面，再把这些文件放进docs/r。docs/file-scrapers.md 的 “R” 一节给出了完整的构建脚本，本文按这条路径走一遍：安装编译依赖 → 编译 R 静态 HTML → 拷贝进docs/r→ 用 scraper 命令验证结果。

先确认 scraper 从哪里读文件

R scraper 的定义在 lib/docs/scrapers/r.rb：

class R < FileScraper self.name = 'R' self.slug = 'r' self.type = 'simple' self.release = '4.4.2' self.root_path = 'doc/html/packages.html' html_filters.push 'r/entries', 'r/clean_html'

FileScraper的读取规则见 lib/docs/core/scrapers/file_scraper.rb：源文件目录是仓库根下的docs拼接 scraper 的 path，也就是docs/r。当该目录缺失时，scraper 会先尝试download_source自动下载——Docs::R没有覆写这个方法（基类默认返回false）——于是直接报错：

The R scraper requires the original documentation files to be stored in the "docs/r" directory.

这确认了两件事：目标目录就是docs/r；而且docs/r/doc/html/packages.html（即root_path）必须是构建产物的一部分，它是抓取入口。

另外两个过滤器决定了最终页面形态，构建时可以对照理解：lib/docs/filters/r/entries.rb 从各包的00Index.html生成条目元数据，lib/docs/filters/r/clean_html.rb 负责去掉每页的 “R Documentation” 表格、页脚等结构。

准备条件

• 一套使用dnf的 Linux 发行版，且有 root 权限：脚本里的依赖安装命令是sudo dnf install，需要执行系统包安装。
• R 编译所需的五个依赖包（脚本原文）：bzip2-devel、gcc-gfortran、libcurl-devel、texinfo、xz-devel。
• DevDocs 本身可运行：README 要求 Ruby 4.0.6、libcurl，以及 ExecJS 支持的 JavaScript 运行时，然后执行gem install bundler和bundle install。
• 以下构建脚本需要在DevDocs 仓库根目录执行，因为DEVDOCSROOT=docs/r是相对路径。

编译 R 静态 HTML 并放入 docs/r

docs/file-scrapers.md 给出的完整脚本如下，可直接照抄：

sudo dnf install bzip2-devel sudo dnf install gcc-gfortran sudo dnf install libcurl-devel sudo dnf install texinfo sudo dnf install xz-devel DEVDOCSROOT=docs/r RLATEST=https://cran.r-project.org/src/base/R-latest.tar.gz # or /R-${VERSION::1}/R-$VERSION.tar.gz RSOURCEDIR=${TMPDIR:-/tmp}/R/latest RBUILDDIR=${TMPDIR:-/tmp}/R/build mkdir -p "$RSOURCEDIR" "$RBUILDDIR" "$DEVDOCSROOT" # Download, configure, and build with static HTML pages curl "$RLATEST" | tar -C "$RSOURCEDIR" -xzf - --strip-components=1 (cd "$RBUILDDIR" && "$RSOURCEDIR/configure" --enable-prebuilt-html --with-recommended-packages --disable-byte-compiled-packages --disable-shared --disable-java --with-readline=no --with-x=no) make _R_HELP_LINKS_TO_TOPICS_=FALSE -C "$RBUILDDIR" # Export all html documentation built − global, and per-package cp -r "$RBUILDDIR/doc" "$DEVDOCSROOT/" ls -d "$RBUILDDIR"/library/*/html | while read orig; do dest="$DEVDOCSROOT${orig#$RBUILDDIR}" mkdir -p "$dest" && cp -r "$orig"/* "$dest/" done

执行前需要了解的变量和参数：

• DEVDOCSROOT=docs/r：产物最终落点，必须与上一节说的 scraper 源目录一致。脚本里的mkdir -p会自动创建它。
• RLATEST：默认下载R-latest.tar.gz。要构建指定版本时，按脚本注释改用R-${VERSION::1}/R-$VERSION.tar.gz路径形式——$VERSION是完整版本号，${VERSION::1}取其第一个字符作为 CRAN 上的目录名（例如4）。
• RSOURCEDIR/RBUILDDIR：源码目录与构建目录，默认在$TMPDIR下，未设置时退回/tmp。整个过程只做 out-of-source 构建，脚本里没有make install，编译结果留在构建目录中，不会向系统安装 R。
• configure的--enable-prebuilt-html是产出静态 HTML 的关键（脚本注释即 “build with static HTML pages”）；--with-recommended-packages、--disable-byte-compiled-packages、--disable-shared、--disable-java、--with-readline=no、--with-x=no均保留脚本原样，文档未逐一解释其含义。
• 最后两段拷贝是“全局 + 每包”两级导出：$RBUILDDIR/doc整体拷入docs/r/doc/，再把每个包的$RBUILDDIR/library/*/html按相同相对路径拷进docs/r/library/<包名>/html/。

构建完成后，docs/r下应当具备 scraper 所需的两类文件：入口docs/r/doc/html/packages.html，以及docs/r/library/<包名>/html/下的各包页面。

用 scraper 命令验证源文件

源文件就位后，按 docs/adding-docs.md 的流程逐项验证：

1. thor docs:list确认r出现在文档列表中（多版本 Ruby 环境下命令需通过bundle exec执行）。
2. 单页验证：thor docs:page r [path]。对FileScraper来说[path]是本地路径，且必须从/开头，否则命令会直接提示ERROR: [path] must be an absolute path.。成功时输出Done，生成的页面出现在public/docs/r/目录；失败时输出Failed!并建议加--debug查看细节。
3. 全量生成：thor docs:generate r --force。成功输出Done；--verbose可看哪些文件被创建/更新/删除，--debug可看被请求和加入队列的 URL，便于定位是哪页把不该抓的链接带进了队列。FileScraper直接读本地文件、没有响应缓存，这一步只依赖docs/r的内容是否完整。
4. 启动应用确认页面渲染：bundle exec rackup后把浏览器指向localhost:9292（首次请求会花几秒编译资源），在应用里启用 R 文档并浏览页面。
5. 最后用thor updates:check r确认显示的 latest version 正确——Docs::R#get_latest_version通过解析 CRAN 的 NEWS 页面（CHANGES IN R x.y.z:行）得到该值。

如果某一步报错，先回到第 2 步用--debug复现单页失败，再检查docs/r里对应路径的文件是否存在、是否为空——FileScraper对每个文件的处理条件是“存在且非空”，空文件会被视为无法处理。

已知限制

• scraper 声明的release目前是4.4.2（见 lib/docs/scrapers/r.rb）。脚本默认构建R-latest，二者版本号不一致这一点文档未说明影响，若你锁定特定版本构建，注意对照release声明自行判断。
• scraper 明确跳过的文件：/DESCRIPTION、/NEWS（含变体）、/doc/index.html、/demo、*.pdf，以及doc/html下的packages-head-utf8.html、Search.html、SearchOn.html、UserManuals.html、faq.html和doc/manual下的R-FAQ、R-admin、R-exts、R-ints、R-lang。构建产物里这些文件会被忽略，属预期行为。
• R scraper 的type是simple，页面样式复用assets/stylesheets/pages/_simple.scss的通用规则，不需要单独的页面 SCSS 文件。
• thor docs:clean会删除文档包和缓存响应，但它不影响docs/r下的源文件；docs/r只有在你重新执行构建脚本前一直是有效来源。

【免费下载链接】devdocsAPI Documentation Browser项目地址: https://gitcode.com/GitHub_Trending/de/devdocs