R 包小插曲

R package vignettes

我有点困惑为什么 "vignettes" 在 R 包中有多个可能的位置。我不明白哪些位置用于什么时间。例如:

devtools::use_vignettes()

在包的根目录下创建一个 vignettes 文件夹

devtools::build_vignettes() 

创建一个 inst/doc 文件夹,该文件夹在构建

时被提升为根目录
pkgdown::build_site()

创建文档文件夹。

由于 background:I 已阅读 H.Wickhams R 包一书,我使用第一个选项创建了几个包,并且一切正常。我会让用户使用 github 安装:

devtools::install_github(pkg,build_vignettes=TRUE)

现在,我刚刚开始参与联合开发一个包,其中使用了第一个和第三个选项。我注意到 vignettes 文件夹中的 .rmd 文件与 docs 文件夹中的 index.html 文件相同。 pkgdown 是否从 vignettes 文件夹复制?

当我从 github(使用 build_vignettes=TRUE)安装时,我也收到一个错误提示安装失败,因为 doc/index.html 路径不能被发现。现在为什么会发生这种情况?

小插曲开发

只有一个地方可以放置原始插图,它在根目录下的插图目录中。这是您在开发包时使用文本和代码示例编写 Rmd 文件的地方。

为您的用户制作小插图

构建小插图时,将编织 Rmd 文件。生成的 html 文件、原始 Rmd 文件和提取的 R 代码将三个文件保存在 inst/doc 目录中。这是将保留在软件包安装中的内容。这是用户将能够阅读的内容。

{pkgdown}

{pkgdown} 正在使用您的 vignette 目录的 Rmd 文件来编织 html 文件,以便它可以为您的包建立一个网站。它还为函数列表和自述文件中的索引构建了一个页面,该文件也用于您的 git 存储库。这不应该保留在 R 包中,用户无法访问。这是为了在互联网上展示您的包裹。

结论

因此,当你开发时,你只需要在 vignette 目录中编写你的 Rmd vignette。其他人会自动保留他们需要的。