如何让RStudio自动编译R Markdown Vignettes?

31
我是一个有用的助手,可以为您翻译文本。

我正在尝试使用R Markdown编写R软件包vignettes。 我正在使用R Studio的软件包作者工具。

我拥有大于版本3.0的R。

我在vignettes文件夹中有一个.Rmd文件,其中包含以下文本:

<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{An Introduction to the bootcorrelations package}
-->

我在我的 DESCRIPTION 文件中有以下内容:
VignetteBuilder: knitr
Suggests: knitr

当我在RStudio中清理和构建或构建和重新加载软件包时,会显示vignette源码,但不显示HTML(即,在inst/man中没有HTML文件)。

enter image description here

如何让RStudio自动从R Markdown Vignette创建HTML文件?

我已经阅读了Yihui关于使用Markdown的R包Vignettes,它建议使用makefile,但这篇更近期的关于knitr vignettes的文档表明不再需要makefile。

我也意识到我可以手动使用类似以下命令创建HTML vignette:

library(knitr)
knit(input='vignettes/foo.Rmd', output='inst/doc/foo.md')
library(markdown)
markdownToHTML('inst/doc/foo.md', 'inst/doc/foo.html')

一个可重现的例子:

Vectorize(dir.create)(c("test", "test/R", "test/man", "test/vignettes"))

cat(
  'Package: test
Title: Test pkg
Description: Investigate how to auto-compile markdown vignettes
Version: 0.0-1
Date: 2015-03-15
Author: Jeromy Anglim
Maintainer: Jeromy Anglim <a@b.com>
Suggests: knitr
License: Unlimited
VignetteBuilder: knitr',
  file = "test/DESCRIPTION"
)

cat(
  '---
title: "Introduction"
author: "Jeromy Anglim"
date: "`r Sys.Date()`"
output: html_document
---

<!--
%\\VignetteEngine{knitr::rmarkdown}
%\\VignetteIndexEntry{Introduction}
-->

# Introduction

A sample vignette!

```{r}
1 + 1
```',
  file = "test/vignettes/intro.Rmd"
)

cat(
  "#' Nothing
#' This function is only needed so that roxygen generates a NAMESPACE file.
#' @export
nothing <- function() 0",
  file = "test/R/nothing.R"
)

library(roxygen2)
library(devtools)

roxygenise("test")
build("test")

为什么需要构建来创建HTML呢?如果你使用R Studio,为什么不使用knit HTML按钮呢?将HTML作为构建的一部分是没有意义的,因为它应该是最小化的,而且vignette可以在安装时创建。 - Tyler Rinker
2
@TylerRinker 我理解你的观点。也许我需要更多地考虑工作流程。我的初始动机是:(a) 将vignette用作附加包测试,(b) 确保文件在github存储库的副本上可访问(例如,在生成的html vigenette上使用http://htmlpreview.github.com/,然后我可以从`readme.md`文件中链接到它);(c) 确保任何以原始文件形式分发的vignette副本都是最新的。 - Jeromy Anglim
我有类似的需求,并使用以下工作流程:(1) 使用knit HTML (2) 使用file.copy将文件复制到Dropbox公共文件夹中 (3) 在GitHub README中使用链接指向Dropbox文件。这对我来说非常有效。PS:之前不知道htmlpreview.github.com,真的很酷。 - Tyler Rinker
我将步骤(2)替换为htmlpreview。谢谢。仍然有一个问题,为什么要构建Vignette。如果这是原因,并且比完整构建快得多,您甚至可以在RStudio中样式化vignette。我认为这个工作流程仍然可以实现您的3个目标。 - Tyler Rinker
1
完全可以扩展 servr,使其能够在浏览器中提供包vignette的服务,如果您想重建vignette,则只需刷新页面即可。我已经在脑海中编写了代码,只需要找些时间将其打出来 :) - Yihui Xie
1个回答

17

更新:从侧面考虑,至少有三种选择。

1. 使用build_vignettes()

正如@Hadley所指出的那样,运行devtools包中的build_vignettes()将构建vignettes并将它们放置在软件包的inst/man目录中。

devtools::build_vignettes()

构建vignette意味着您将在inst/man目录下获得三个版本:

  1. Rmd源文件
  2. 编织或编译的HTML vignette
  3. 代码块中的R代码

这与RStudio的构建和重新加载命令无关,但它是一种解决此任务的一行代码。并且可以轻松地纳入到makefile中。

2. 在Rstudio中使用Knit HTML

正如@TylerRinker所述,您只需在Rstudio中使用Knit HTML即可。这将在vignettes目录中添加rmd vignette的md和HTML编织版本。

这也与构建过程无关,但正如@TylerRinker所指出的那样,通常您不希望vignette与主要构建过程相关联。这还具有提供md文件的好处,该文件可以作为在github上显示vignette的良好选项,尽管http://htmlpreview.github.com/是在github上显示HTML vignette的一个选项。

3. 构建源包并从压缩文件中提取

Build - Build Source Package在RStudio中对应于R CMD build。运行时,将创建一个压缩的tar.gz文件,其中包含原始rmd vignette文件的inst/doc目录中的Rmd、R和HTML文件。

这在撰写软件包vignettes的官方文档中有所描述,该文档指导您使用R CMD build生成PDF和HTML vignettes。

因此,您可以

  1. 构建源代码
  2. 解压tar.gz文件
  3. 浏览并打开结果文件

3
您可以使用 devtools::build_vignettes() 进行构建文档。 - hadley
1
唯一的关键是 R CMD build;这是获取已编译的vignettes放入HTML帮助文件中vignette索引的官方方法。目前,RStudio仅支持R CMD INSTALL,但我不认为这总是一个好主意,例如,它不会构建vignettes。如果没有人提到此问题,我将在支持论坛中提及它。 - Yihui Xie
您能否提供一个使用 build_vignettes() 的示例 makefile? - StevieP
另外,@hadley,在build_vignettes()的帮助文档中存在一个不明确的代词:.Rbuildignore中应包含哪些文件,是vignettes/目录中的文件还是inst/doc/目录中的文件? - StevieP
2
所以,我正在使用RStudio版本0.98.836,但这些选项都不起作用。特别是,build_vignettes()返回NULL,尽管在vignettes/中有一个真正的.Rmd文件,并且knit HTML不会在vignettes/中保存.md或.html文件...为什么会这样? - StevieP

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接