knitr .Rmd文档在vignette()中不显示

Question

在我正在使用R Studio开发的一个包中，我通过devtools::use_vignette("mydoc.Rnw")来创建文档，这会生成标准的vignette头部信息。

---
title: "Title"
author: "Michael Friendly"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

我已经按照http://yihui.name/knitr/demo/vignette/和http://r-pkgs.had.co.nz/vignettes.html中的所有说明进行操作。该软件包的CRAN页面上列出了文档，但在加载软件包的R会话中似乎无法访问这些文档。

 > browseVignettes("matlib")
 No vignettes found by browseVignettes("matlib") 

> library(tools)
> names(vignetteEngine(package = 'matlib'))
Error in getEngine(name, package) : 
  None of packages ‘matlib’ have registered vignette engines

我知道该包含有使用knitr处理的.Rmd范例的其他软件包，但我不知道为什么我的软件包没有。有什么缺失吗？

我的vignettes/目录中只包含.Rmd文件（没有PDF文件），但这似乎与例如https://github.com/yihui/knitr/tree/master/vignettes相同。

- user101089

---

你是否在配置构建工具时勾选了“使用roxygen生成vignettes”框，并在安装软件包时构建vignettes？ - rawr

我现在已经勾选了“使用roxygen生成vignettes”框，并且“构建和重新加载”现在会在“vignettes/”目录中生成HTML文件。然而，当我运行browseVignettes("matlib")时仍然提示“未找到vignettes”。 - user101089

关于这个过程还有进一步的问题：vignettes/*.html 应该添加到 .gitignore 还是 .Rbuildignore 中？ - user101089

啊！我需要运行 devtools::build_vignettes()。这将把 vignettes/*.html 文件移动到 inst/doc 目录并将 inst/doc 添加到 .gitignore 中。 - user101089

Vignette是软件包的一部分，不应被忽略。可以忽略已构建的Vignette，因为它会在每次构建时重新构建。 - Roman Luštrik

Answer 1

注意，当你使用devtools::install()从目录安装软件包时，默认情况下devtools不会构建文档（vignettes），同样适用于某些install_*函数，如install_github()。你必须在安装软件包时指定build_vignettes = TRUE参数来构建文档。如果您只使用RStudio按钮Build & Reload，则目前没有使用devtools构建文档的方法。您需要Build Source Package并在tarball上运行R CMD INSTALL，或在R控制台中运行devtools::install(build_vignettes = TRUE)。

- Yihui Xie

---

这明确了很多事情。在http://yihui.name/knitr/demo/vignette/上添加一些内容可能会很有用。 - user101089

@user101089 好的建议。我会去做的。 - Yihui Xie

Answer 2

嗯，我找到了一种黑科技可以解决这个问题。

在RStudio的配置构建工具...中，我们可以为Build & Reload按钮自定义R CMD INSTALL的选项。在当前的实现中，它的行为类似于在包目录的父级目录运行R CMD INSTALL [options] pkg。

事实证明，这些选项可以是任意字符串，甚至包括;，因此使我们能够运行bash命令。

例如，我们可以指定-v; cd pkg; cp vignettes/*html inst/doc; R CMD INSTALL --no-multiarch --with-keep.source .; echo

这样，-v将使RStudio的R CMD INSTALL无效。然后，我们可以在使用我们自己的R CMD INSTALL安装软件包之前将构建的html文件从vignette/复制到inst/doc/。（cd pkg;使我们不需要在后续命令中多次输入软件包名称。 echo使RStudio附加的软件包名称失效。

我知道这个技巧有很多缺点，比如硬编码软件包名称，如果软件包名称在后期更改，这种方法容易出错。

请自行决定是否使用该技巧。

希望RStudio能尽快推出一个更加优雅的解决方案。

- Zhuoer Dong

Answer 3

在我的端上，使用devtools::install(build_vignettes = TRUE)可以解决vignettes的问题：browseVignettes("mypackage")会正常工作。但每次我尝试打开帮助文件?myfunction时，都会出现错误提示：

Error in fetch(key) : lazy-load database 
'/Library/Frameworks/R.framework/Versions/3.6/Resources/library/mypackage/help/mypackage.rdb' is corrupt

在我看来，解决这两个问题的最安全的方法是执行 R CMD build mypackage 和 R CMD INSTALL mypackage.1.0.tar.gz。

- Yu Yang