R object documentation: Package documentation as first item

Question

I have an R package and I want to display the general information about the package as first item in the created PDF manual.

I use roxygen2 (version 7.0.2) for creating the documentation and followed the instructions given here . When I create the documentation, the items appearing in the manual are all ordered alphabetically, including the item for the general documentation. But, of course, I want to have the general documentation at the top.

It seems that putting the package documentation item first must work somehow because it works in the manual of knitr .

My setup: I created a package "TestPackage" using RStudio, with one "hello.R" file:

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

and one "TestPackage.R" file with the general documentation for the package.

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

When I run,

R CMD Rd2pdf TestPackage

I get a PDF manual with the first item "hello" and then the item "TestPackage".

How can I achive that the item for the package comes first?

Answer 1

In order to ensure that the package documentation entry is first in the manual, you need its name to be <packagename>-package (where you replace <packagename> with the name of your package). Here you could accomplish that by changing

#' @name TestPackage

to

#' @name TestPackage-package

Why is this the case? Well, as always when you run into some strange corner of R package development, the best thing you can do is to consult the Writing R Extensions manual . Here, we'd want to look at Section 2.1, Rd format (the documentation files in R are in a format called Rd ; roxygen creates the Rd files in man/ for you). Specifically, in Section 2.1.1, we see

\\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.

That footnote 102 tells us

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.

So, you have to name the Rd file as pkgname-package to move it to the top of the manual.