Best practices for documenting re-exports?

I've been trying to figure out how dplyr's pkgdown-generated reference site builds this page on re-exports. I can't find anything in the dplyr repo that specifies that page (in particular, I don't see any reference to such a page in _pkgdown.yml). I also can't find any explicit mention of special 're-export' handling in roxygen2's docs.

On the specific re-exported functions in dplyr, I see various @name and @rdname pairings ... setops (in sets.r) being a perfectly good example. But I can't find any structure that says setops should be documented on that re-exports page by pkgdown :-/

Does anyone know how that re-exports page is (seemingly automatically) built?

BTW, I (naïvely?) tried something like the below, and roxygen2/pkgdown don't build a re-export page even when named explicitly, so clearly I'm doing something wrong!

#' Re-exports
#'
#' This description causes roxygen2 to throw a warning.
#'
#' @name re-exports
NULL

#' @rdname re-exports
#' @importFrom magrittr `%>%` `%T>%`
#' @export
magrittr::`%>%`
#' #export
magrittr::`%T>%`
 
#' @rdname re-exports
#' @importFrom mypkg foo bar
#' @export
mypkg::foo
#' #export
mypkg::bar

(And while we're on the topic, is there an easier/more-concise pattern for re-exports ... or is this still the standard best practice?)

1 Like

I've mostly figured this out, though it required reading through roxygen2's tests to understand the implicit behavior (as I couldn't find any formal documentation on this topic).

The short recipe is:

  1. Re-export using this roxygen2 tag pattern:
    #' @importFrom pkg symbol
    #' @export
    pkg::symbols
    
    (The explicit :: notation is required.)
  2. Do *not add other tags. In particular, avoid the @description tag (or it's implied text as the second #' paragraph)
  3. Upon building your docs (e.g. via devtools::document()) this will create an .Rd help topic called "reexports". (You can see that topic now with ?yourpkg::reexports.)
  4. By default, pkgdown::build_site() will not include the "reexports" topic, so you'll need to explicitly add it to your _pkgdown.yml config file, like so:
    reference:
    - title: some section
    - contents:
      - topic1
      - topic2
      - reexports
    

Hopefully this is helpful to others that want to re-export some objects/functions.

3 Likes

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.