R 对象文档：将文档打包为第一项

Question

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

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

似乎将包文档项放在首位必须以某种方式起作用，因为它在 manual of knitr.

中起作用

我的设置：我使用 RStudio 创建了一个包 "TestPackage"，其中有一个 "hello.R" 文件：

#' 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

到

#' @name TestPackage-package

为什么会这样？好吧，一如既往，当你运行进入 R 包开发的某个奇怪角落时，你能做的最好的事情就是查阅 Writing R Extensions manual. Here, we'd want to look at Section 2.1, Rd format（R 中的文档文件的格式称为 Rd; roxygen 在 man/ 中为您创建 Rd 个文件）。具体来说，在2.1.1节中，我们看到

\name{name}

name typically¹⁰¹ is the basename of the Rd file containing the documentation. ... Entries in the package manual will be in alphabetic¹⁰² order of the \name entries.

脚注 102 告诉我们

in the current locale, and with special treatment for LaTeX special characters and with any ‘pkgname-package’ topic moved to the top of the list.

因此，您必须 name Rd 文件 pkgname-package 才能将其移动到手册的顶部。

R 对象文档：将文档打包为第一项

R object documentation: Package documentation as first item

r

documentation-generation

roxygen2