Skip to contents

How to update documentation

Source: vignettes/HowToUpdateDocumentation.Rmd
HowToUpdateDocumentation.Rmd

Roxygen2 and Pkgdown

Roxygen2-style comments are how we generate most content.

Example:

##' TileDB Cloud Manual Layer for Array Info
##'
##' This function shows array information on TileDB Cloud.
##'
##' Nominally you will first call \code{\link{login}}; if not, the results of
##' the last login at \code{~/.tiledb/cloud.json} will be used.
##'
##' @param namespace Like "TileDB-Inc"
##'
##' @param arrayname Like "quickstart_dense"
##'
##' @return A list of array properties
##' @export
array_info <- function(namespace, arrayname) {
  apiClientInstance <- get_api_client_instance()
  arrayApiInstance <- ArrayApi$new(apiClientInstance)
  # The $toJSON() converts from R6 class to R named list.
  # That in turn is nicely printable using str().
  arrayApiInstance$GetArrayMetadata(namespace, arrayname)$toJSON()
}

Notes:

  • The first sentence will become the title – used as one-line summary in the docs/reference/index.html reference page, and HTML/H1-style title when someone clicks through the link to the docs/reference/name-of-the-function.html details page.
  • The second sentence will become summary text under the title in the docs/reference/name-of-the-function.html details page.
  • The remaining bits will become the Details section in the docs/reference/name-of-the-function.html details page.
  • Use \code{\link{...}} for in-package function references; use \code{...} for any other program text.
  • The @param and @return are used for autogenerating the docs/reference/name-of-the-function.html details page.
  • The @export tag is used by Roxygen2 to populate the NAMESPACE file. Note however that even non-exported functions will regardless appear in the docs/reference/index.html reference page. It’s handy to name these with a leading . which matches a rule in our _pkgdown.yml, placing these functions in their own section at the bottom of the docs/reference/index.html reference page.
  • The code autogenerated by OpenAPI already follows these conventions.

_pkgdown.yml

See this repo’s _pkgdown.yml for the reference and articles syntax which allow us to control section-ordering for reference and articles (vignettes).

The rule in the reference section is that items starting with a-z are manual-layer functions; those starting with A-Z are OpenAPI-autogen functions/classes; those starting with . are package-internal. As long as you follow these naming conventions for the code you write, you shouldn’t need to modify _pkgdown.yml when you write new functions.

For new articles (vignettes), by contrast, you will need to add the information for your new vignette to _pkgdown.yml.

Build steps

After install.packages("roxygen2") and install.packages("pkgdown") you should do roxygen2::roxygenise(). These outputs go into source control.

You can optionally do pkgdown::build_site and open docs/index.html to preview HTML locally and check that the rendering is as desired, but, be sure not to commit any of these outputs to source control.

How this works:

Publishing

See HowToRelease.md.