pjt222 编写 Vignette
为 R 包创建长篇文档 vignette。
适用场景
- 为包添加"入门"教程
- 记录跨多个函数的复杂工作流
- 创建领域特定指南（如统计方法）
- CRAN 提交要求提供函数帮助页之外的用户文档
输入
- 必需：含待记录函数的 R 包
- 必需：Vignette 标题和主题
- 可选：格式（R Markdown 或 Quarto，默认：R Markdown）
- 可选：Vignette 是否需要外部数据或 API
步骤
第 1 步：创建 Vignette 文件
usethis::use_vignette("getting-started", title = "Getting Started with packagename")
预期结果： vignettes/getting-started.Rmd 已创建，包含 YAML frontmatter。knitr 和 rmarkdown 已添加至 DESCRIPTION Suggests 字段。vignettes/ 目录已存在。
失败处理： 若 usethis::use_vignette() 失败，确认工作目录是包的根目录（包含 DESCRIPTION）。若 knitr 未安装，先运行 install.packages("knitr")。若需手动创建，创建 vignettes/ 目录和文件，确保 YAML frontmatter 包含全部三个 %\Vignette* 条目。
第 2 步：编写 Vignette 内容
---
title: "Getting Started with packagename"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Getting Started with packagename}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## Introduction
Brief overview of what the package does and who it's for.
## Installation
```r
install.packages("packagename")
library(packagename)
Basic Usage
Walk through the primary workflow:
# Load example data
data <- example_data()
# Process
result <- main_function(data, option = "default")
# Inspect
summary(result)
Advanced Features
Cover optional or advanced functionality.
Conclusion
Summarize and point to other vignettes or resources.
**预期结果：** Vignette Rmd 文件包含"介绍"、"安装"、"基础用法"、"高级功能"和"总结"章节。代码示例使用包的导出函数并产生可见输出。
**失败处理：** 若示例运行失败，使用 `devtools::install()` 确认包已安装。确保示例在 `library()` 调用中使用包名（而非 `devtools::load_all()`）。对于需要外部资源的函数，使用 `eval=FALSE` 仅展示代码而不执行。
### 第 3 步：配置代码块
为不同目的使用代码块选项：
```r
# 标准执行块
{r example-basic}
result <- compute_something(1:10)
result
# 展示代码但不运行（用于说明目的）
{r api-example, eval=FALSE}
connect_to_api(key = "your_key_here")
# 运行但隐藏代码（仅显示输出）
{r hidden-setup, echo=FALSE}
library(packagename)
# 设置全局选项
{r setup, include=FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7,
fig.height = 5
)
预期结果： 带有 include=FALSE 的 setup 块设置全局选项（collapse、comment、fig.width、fig.height）。代码块配置适当：说明性代码使用 eval=FALSE，隐藏设置使用 echo=FALSE，交互示例使用标准块。
失败处理： 若代码块选项不生效，确认语法使用 {r chunk-name, option=value} 格式（逗号分隔，逻辑值不加引号）。确认 setup 块通过放置在文档顶部来最先运行。
第 4 步：处理外部依赖
对于需要网络访问或可选包的 vignette：
{r check-available, include=FALSE}
has_suggested <- requireNamespace("optionalpkg", quietly = TRUE)
{r use-suggested, eval=has_suggested}
optionalpkg::special_function()
对于耗时计算，预计算并保存结果：
# Save pre-computed results to vignettes/
saveRDS(expensive_result, "vignettes/precomputed.rds")
# Load in vignette
{r load-precomputed}
result <- readRDS("precomputed.rds")
预期结果： 外部依赖处理得当：可选包使用 requireNamespace() 条件加载，依赖网络的代码使用 eval=FALSE 或 tryCatch()，耗时计算使用预计算的 .rds 文件。
失败处理： 若 vignette 因可选包不可用而在 CRAN 上失败，用条件变量包裹相关部分（如 eval=has_suggested）。对于预计算结果，确认 .rds 文件包含在 vignettes/ 目录中并以相对路径引用。
第 5 步：构建并测试 Vignette
# Build single vignette
devtools::build_vignettes()
# Build and check (catches vignette issues)
devtools::check()
预期结果： Vignette 构建无错误。HTML 输出可正常阅读。
失败处理：
- 找不到 pandoc：在
.Renviron中设置RSTUDIO_PANDOC - 包未安装：先运行
devtools::install() - 缺少 Suggests 包：安装 DESCRIPTION Suggests 中列出的包
第 6 步：在包检查中验证
devtools::check()
与 Vignette 相关的检查：正确构建、构建时间合理、无错误。
预期结果： devtools::check() 通过，无 vignette 相关错误或警告。Vignette 在 CRAN 时间限制内构建完成（通常不超过 60 秒）。
失败处理： 若 vignette 导致检查失败，常见修复包括：在 DESCRIPTION 中添加缺少的 Suggests 包、对慢速块使用 eval=FALSE 减少构建时间、确保 VignetteIndexEntry 与标题匹配。单独运行 devtools::build_vignettes() 以隔离 vignette 特定错误。
验证清单
- Vignette 通过
devtools::build_vignettes()构建无错误 - 所有代码块正确执行
- VignetteIndexEntry 与标题匹配
-
devtools::check()通过且无 vignette 警告 - Vignette 出现在 pkgdown 站点文章中（若适用）
- 构建时间合理（CRAN 要求 < 60 秒）
常见问题
- VignetteIndexEntry 不匹配：YAML 中的索引条目必须与用户在
vignette(package = "pkg")中看到的内容一致 - 缺少
vignetteYAML 块：三行%\Vignette*均为必需 - Vignette 对 CRAN 而言过慢：预计算结果或对耗时操作使用
eval=FALSE - 找不到 pandoc：确认已设置
RSTUDIO_PANDOC环境变量 - 引用包自身：在 vignette 中使用
library(packagename)而非devtools::load_all()
相关技能
write-roxygen-docs— 补充 vignette 教程的函数级文档build-pkgdown-site— Vignette 在 pkgdown 站点中作为文章显示submit-to-cran— CRAN 对 vignette 有特定要求create-quarto-report— 作为 R Markdown vignette 替代方案的 Quarto