CODEWITHSUNDEEP
rroxygen2
Wasabi
Wasabi

Reputation: 3061

Is a package's help index page customizable?

The help() function allows us to see an index with a list of all functions within a package:

help(package=stats)

If the package is very large, the help page will be automatically broken down alphabetically, with links to each section by initial letter (as in the case of stats). Smaller packages will have all the functions together in alphabetical order.

Is this index page customizable?

I'm using roxygen2, and would love to be able to group functions by their @family.

Upvotes: 2

Views: 179

Answers (2)

dash2
dash2

Reputation: 2262

From "writing R extensions":

The optional file INDEX contains a line for each sufficiently interesting object in the package, giving its name and a description (functions such as print methods not usually called explicitly might not be included). Normally this file is missing and the corresponding information is automatically generated from the documentation sources (using tools::Rdindex()) when installing from source.

The file is part of the information given by library(help = pkgname).

Rather than editing this file, it is preferable to put customized information about the package into an overview help page (see Documenting packages) and/or a vignette (see Writing package vignettes).

So the answer is yes, but they don't recommend it.

One option would be to organize the index file other ways than alphabetically. You can do this by passing a named vector of .Rd help files to tools::Rdindex:

tools::Rdindex(c("../santoku/man/dissect.Rd", "../santoku/man/percent.Rd", ...))
dissect                 Cut data into intervals, then separate out
                        common values
percent                 Simple percentage formatter
...

Upvotes: -1

Waldi
Waldi

Reputation: 41220

See section 10.6 of R Packages :

You can use roxygen to provide a help page for your package as a whole.

you need to document NULL, and then manually label it with @docType package and @name . This is also an excellent place to use the @section tag to divide up page into useful categories.

Just create an mypackage.R file with the above Roxygen tags applied to NULL:

#' Mypackage: A package I created
#'
#' MyPackage has different families of functions described below
#' 
#' @section Some functions:
#' * [mysum()] 
#' * [myprod()]
#' 
#' @section Other functions:
#' * [other()]
#' * [foo()]
#'
#' @docType package
#' @name mypackage
NULL

The brackets [] allow to create links to the functions of the package.

Upvotes: 2

Related Questions