如何为R包“预建"小插图索引? [英] How do I 'prebuild' a vignette index for an R package?

问题描述

我正在准备要提交给 CRAN 的软件包. 我先使用R CMD build myPackage，然后使用R CMD check myPackage --as-cran，它通过所有检查，没有注释或警告. 但是，每次尝试提交时，都会从一位CRAN维护者那里收到以下错误消息:

I'm preparing a package for submission to CRAN. I use R CMD build myPackage then R CMD check myPackage --as-cran and it passes all checks with no notes or warnings. However, each time I try to submit, I get the following error message from one of the CRAN maintainers:

Package有一个VignetteBuilder字段，但没有预建的小插图索引.

Package has a VignetteBuilder field but no prebuilt vignette index.

首先，我希望能够在自己的系统(R version 3.0.1)上重现以上错误消息.

As a start, I'd like to be able to reproduce the above error message on my own system (R version 3.0.1).

小插图.Rnw文件如下所示:

%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{myVignetteName}
\documentclass{article}
\begin{document}
Here is some code:
<<>>=
plot(1:10, 10:100)
@
\end{document}

我尝试在根目录中添加带有这样的插图插图的INDEX文件:

I have tried adding an INDEX file in the root directory with a vignette entry like this:

myFunction       a brief description
abc-vignette     vignette description

同样，这通过了R CMD check myPackage --as-cran，但是我得到了相同的错误消息.

Again, this passes R CMD check myPackage --as-cran but I get the same error message.

我还尝试过R CMD build myPackage --md5强制创建MD5文件，但无济于事.

I have also tried R CMD build myPackage --md5 to force creation of an MD5 file, to no avail.

当我查看myPackage.Rcheck/00_pkg_src/myPackage/inst/doc时，可以找到小插图文件.Rnw和.pdf.

When I look at myPackage.Rcheck/00_pkg_src/myPackage/inst/doc I find the vignette files, .Rnw and .pdf as expected.

软件包DESCRIPTION文件具有以下条目:

The package DESCRIPTION file has the following entry:

VignetteBuilder: knitr
Suggests: knitr

当我查看myPackage.Rcheck/myPackage/Meta时，我看到一个条目vignette.rds.但是，这似乎是一个二进制文件，因此我无法理解.

When I look at myPackage.Rcheck/myPackage/Meta I see an entry vignette.rds. However this appears to be a binary file, so I can't make sense of it.

这来自编写R扩展名":

This is from 'writing R extensions':

在安装时，将自动创建包中所有小插图的HTML索引 从\ VignetteIndexEntry语句中获取，除非文件"inst/doc"中存在文件"index.html".该索引从软件包的HTML帮助索引链接.如果确实提供了"inst/doc/index.html"文件，则该文件应仅包含指向已安装的"doc"目录下文件的相对链接，或者可能(不是真正的索引)指向HTML帮助文件或"DESCRIPTION"文件的相对链接.

At install time an HTML index for all vignettes in the package is automatically created from the \VignetteIndexEntry statements unless a file ‘index.html’ exists in directory ‘inst/doc’. This index is linked from the HTML help index for the package. If you do supply a ‘inst/doc/index.html’ file it should contain relative links only to files under the installed ‘doc’ directory, or perhaps (not really an index) to HTML help files or to the ‘DESCRIPTION’ file.

所以我需要手动创建index.html，并且有人可以指出它的外观示例吗?

So do I need to manually create index.html and could anyone point to an example of what this should look like?

此问题似乎密切相关，但我(不知道)没有.Rbuildignore文件. 这也相关，尽管我没有使用devtools进行软件包创建.我还查看了这个问题，但不是看到一个简单的答案.

This question appears closely related, but I do not (knowingly) have an .Rbuildignore file. This is also related, although I'm not using devtools for package creation. I have also looked at this question but am not seeing an easy answer.

更新7月1日

对于一个可复制的示例，可在github上的此处获得该程序包.下载并安装(例如，使用devtools::install_github()应该可以重现此错误.

For a reproducible example, the package is available here on github. Downloading and installing (e.g. with devtools::install_github() should allow this error to be reproduced.

推荐答案

我收集了Vignette命令，它们必须位于 preamble 中，即位于documentclass下面，以便文件应该显示为:

I gather the Vignette commands need to be in the preamble, i.e. below documentclass, so that the file myVignette.Rnw should read:

\documentclass{article}

% \VignetteIndexEntry{myVignette}
% \VignetteEngine{knitr::knitr}

\usepackage[]{graphicx}
...

这似乎很好.

错误消息来自R CMD check的开发版本版本，当前版本为3.3.0.我一直在使用较旧的稳定"版本，考虑将其提交给CRAN时，推荐的方式不是 .

The error message is from the development version of R CMD check which is currently 3.3.0. I have been using the older 'stable' version which is not the recommended way to check packages when considering submission to CRAN.

我仍然不确定使用手动文件index.html的优点-似乎没有必要，但是如果有人可以对此有所了解，我将很乐意更改已接受的答案.

I'm still not sure of the merits of using a manual index.html file - it appears unnecessary but I will gladly change the accepted answer if anyone can throw some light on this.

这篇关于如何为R包“预建"小插图索引?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！