Add sections to R package's help/documentation

Question

Some R packages (e.g., ggplot2, dplyr,devtools etc.) have alphabetically entitled sections in their help/documentation and a bar of links to those sections (indicated by red arrows in picture below). Other packages (e.g., RcmdrMisc) don't have.

How can I add these elements to may R package's help?

I use roxygen2 for documentation.

Vivanvivarium

Good question! I guess the source code of the packages could give an answer (if nobody here knows it). – Katharinakatharine

As far as I know, these index files are auto-generated. At least, my packages always have them, but I never write them. I always thought that these letters are added automatically, once the list of functions gets long enough. But I might be wrong. – Bourn

I studied a structure of a few packages on GitHub, but did not find out how to make that alphabetical index yet. – Vivanvivarium

@Bourn How many functions are there in your package, which has index with sections? I wonder, how many should be included, to have these sections. – Vivanvivarium

Answer 1

In the Writing R Extensions file (included with every copy of R from CRAN) is a small section regarding the INDEX file:

1.1.4 The INDEX file

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.

When packages have an index file, the HTML code is in the html folder.

Cumulative

I found that html folder in installed version of my package, but I still don't understand, how to make sections. Is function tools::Rdindex() responsible for making the HTML file with index during installation of a package? – Vivanvivarium

even if the INDEX files has a special order for objects, the final ordering is alphabetical. Also does not have possibility for sections. (see gtools for ex.) – Bunkum

Correct. User2554330 added a useful pointer a couple of months age to the pkgdown::build_reference function that does support sections. I suspect that facility was not available when the question first appeared. MrFlick added a point that explains why some pkg Indexes have first letter "sections" and others do not. (It is not under user control.) – Cumulative

Answer 2

The help index page is automatically generated by R when you install a package. But note that the alphabetical index is only generated when there are more than 100 items on the index page. There is currently no way to change that behavior. I found that in the code for installing packages

Manufactory

You can generate your own INDEX page. "Writing R extensions" says so, at any rate. – Plasticizer

@Plasticizer You can generate your own INDEX file, but what you see in the help screen is not the raw contents of the INDEX file. The INDEX just lists all the functions and their descriptions. For example you can view the index file for a package with readLines(system.file("INDEX", package="lattice")). There is still no way to create sections in the visual listing as far as I can tell. If you found some way to do it, please share as an answer below. – Manufactory

Answer 3

As @iRTFM and @MrFlick say, you can't affect the index displayed by R. However, if you use the pkgdown package to make a package web page, you have full control over the main index for the help pages. For example, see

https://ggplot2.tidyverse.org/reference/index.html

The description about how that index was specified is given in the help page ?pkgdown::build_reference, which is displayed here:

https://pkgdown.r-lib.org/reference/build_reference.html

Taddeusz