Arbitrary sections in roxygen docs

Question

The way Roxygen seems to work is that the first line is the \title, everything else is in the \details, and then any @foo directives handle those things. But R documentation is richer than that. I can have "\section{Llamas}{Are they ungulates?}" in .Rd files.

But I can't get Roxygen to do anything other than wrap it all in \details. Am I missing something?

I have a hacky solution, which is to stick an unmatched } before my \section. This then ends the \details section. I then have to not put an ending } in, because roxygen sticks one in thinking its closing the \details. Eeeeeurrrrrrrrgh.

Waltner

Excellent question. I suspect you are correct that this can't be done at the moment. But Hadley Wickham recently mentioned that he how hold the key to future development of roxygen, so I am hopeful that something amazing will appear in the near future. – Dyspnea

Depending on how in-depth you want to get, you might offer to help Hadley with what he's doing. I know his work is amazing, but after all, 'Vell, he's just zis guy, you know ?'. You might want to peruse the code Hadley has published at github github.com/hadley/roxygen and maybe send him an email and ask him... – Metaphor

Sure. I've seen Hadley on here too, so he may be aware. At first I thought I'd missed something in the docs, like an "@section Llamas" directive or similar. – Waltner

I sure do like llamas. That is all. – Courtyard

See the @section tag in roxygen2 – Gurney

Answer 1

This support has been added (at least in roxygen2). You just need to add @section Llamas: and then anything after that until a new directive is met will be in a Llamas section. Here is an example

#' Llama llama llama
#' 
#' More about llamas
#' 
#' @section Llamas:
#' Are they ungulates?
#' 
#' @section Not llamas:
#' This section is not about llamas.  It is not very interesting.
#' 
#' @param notused A parameter that isn't used at all!
#' @export
llama <- function(notused){
    return("LLAMA LLAMA LLAMA")
}

which gives the following for the .Rd file

\name{llama}
\alias{llama}
\title{Llama llama llama}
\usage{
  llama(notused)
}
\arguments{
  \item{notused}{A parameter that isn't used at all!}
}
\description{
  More about llamas
}
\section{Llamas}{
  Are they ungulates?
}

\section{Not llamas}{
  This section is not about llamas.  It is not very
  interesting.
}

Dravidian

Note that the section title cannot contain any colon :. – Try