In the user tutorial and in the code examples in the documentation of each datashield function, logging in to VMs or remote servers can be accomplished using the data() function to access the required login details. For example:

  > library(dsBaseClient)
  > data(logindata)
  > logindata

The logindata object is available because it is part of the (in this case) dsBaseClient package.

In the source code, it is stored as a .rda file in the data/ folder of the package. See the dsBaseClient code on GitHub.

Creating new data objects to be bundled with a client package is a three step process:

1. Create the object in R

For example, construct a dataframe containing datashield login details:

  > server <- c("study0", "study1")
  > url <- c("192.168.56.100:8080", "192.168.56.101:8080")
  > user <- "administrator"
  > password <- "password"
  > table <- c("DASIM.DASIM", "DASIM.DASIM")
  > DASIM_logindata <- data.frame(server,url,user,password,table)

2. Save the object as a .rda file

  > save(DASIM_logindata, file='DASIM_logindata.rda', ascii=TRUE)

The option ascii=TRUE creates a text file, rather than a binary file.

3. Add to the client package

Move the .rda file into dsBaseClient/data, add and commit the file, then push to GitHub.

Documenting packages and data

Documentation for datashield functions is written as a header to the function itself. That is to say, as a header within files like R/some_function.R.

The roxygen2 package is used to turn these headers into the .Rd files found in the man/ folder for each package. Those .Rd files can be (re)generated by the devtools::document() function or equivalently by the roxygen2::roxygenise() function.

When a package is installed, this documentation is available from ?<function name> or help(<function name>).

What if you want to write documentation for something other than a function?

For example:

• The whole package.
• Some data that is included with the package (such as the 'logindata' for the VMs).

Create a .R file in the R/ folder. But instead of documenting a function, document NULL.

To illustrate, consider the file dsBaseClient.R

    #' 
    #' @docType
    #' package
    #'
    #' @name
    #' dsBaseClient
    #'
    #' @title
    #' The base DataSHIELD client package
    #' 
    #' @description
    #' This packages contains the basic client functions for using DataSHIELD 
    #'
    #' @details
    #' For a list of all functions available in dsBaseClient, run:
    #' \code{ls('package:dsBaseClient')}
    #'
    NULL

The tag @docType package indicates that this documentation refers to the dsBaseClient package itself, rather than a function within it.Alternatively, you could use the tag @docType data to indicate that the documentation refers to some data bundled with the package.