CODEWITHSUNDEEP
rdocumentation-generationroxygen2
esel
esel

Reputation: 983

R object documentation: Package documentation as first item

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?

Upvotes: 2

Views: 246

Answers (1)

duckmayr
duckmayr

Reputation: 16940

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 typically101 is the basename of the Rd file containing the documentation. ... Entries in the package manual will be in alphabetic102 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.

Upvotes: 2

Related Questions