R对象文档：包装文档为第一项

Question

我有一个R软件包，我想在创建的PDF手册中作为第一个项目显示有关该软件包的一般信息。

我使用roxygen2（版本7.0.2）创建文档，并遵循here给出的说明。创建文档时，手册中出现的项目均按字母顺序排列，包括常规文档的项目。但是，当然，我想将常规文档放在顶部。

似乎首先将软件包文档项放在第一位必须起作用，因为它可以在manual of knitr中起作用。

[我的设置：我使用RStudio使用一个“ hello.R”文件创建了一个包“ TestPackage”：

#' Hello world function
#'
#' Prints "Hello, world!"
#'
#'@return nothing interesting
hello <- function() {
  print("Hello, world!")
}

和一个“ TestPackage.R”文件以及该软件包的一般文档。

#' A test package
#'
#' @docType package
#' @name TestPackage
NULL

我跑步时，

R CMD Rd2pdf TestPackage

我得到的PDF手册的第一项是“ hello”，然后是项“ TestPackage”。

如何使包装的物品排在最前面？

Answer 1

为了确保包装文档条目在手册中排在首位，您需要将其name设置为<packagename>-package（将<packagename>替换为包装名称）。在这里，您可以通过更改

完成此操作

#' @name TestPackage

to

#' @name TestPackage-package

为什么会这样？好吧，和往常一样，当您遇到R包开发的某个陌生角落时，您可以做的最好的事情是咨询Writing R Extensions manual。在这里，我们想看一下Section 2.1, Rd format（R中的文档文件格式为Rd； roxygen为您创建Rd中的man/文件）。具体来说，在2.1.1节中，我们看到

\ name {name}

通常为¹⁰¹是包含文档的Rd文件的基本名称。 ...软件包手册中的条目将按照\ name条目的字母¹⁰²顺序。

脚注102告诉我们

在当前语言环境中，对LaTeX特殊字符进行了特殊处理，并且所有“ pkgname-package”主题均移至列表顶部。

因此，您必须将name文件以Rd的形式pkgname-package移至手册的顶部。