Convert ergm-terms documentation to Roxygen?

[krivit]

At the moment, all the ergm terms are documented in one big file (ergm-terms.Rd) with a "standard" syntax for keywords. Porting them to Roxygen (somehow) would greatly simplify maintenance in the following ways:

• Documentation "source" could be placed next to the InitErgmTerm function definitions, for much better maintainability.
• Using @template, common bits of text (like meanings of arguments common among many terms) only need to be written and updated once.
• Markdown is less clunky than the Rd format.

AFAIK, roxygen2 has an API for custom @ tags and document types, and we could write them to generate automatically formatted Rd files. Some other things we might be able to do:

• Generate a help file for each term and a help file with all the terms and/or a term index. This would allow us to link to a specific term's help.
• @seealso-style cross-referencing for related terms.

Any thoughts?

[krivit]

Another possibility is to use the dynamic pages mechanism, which could also be used to make help("ergm-terms") list all terms defined so far. E.g., something like this:

1. Each InitErgmTerm.*() function is to be able to define attr attributes that document it. For example,

   InitErgmTerm.absdiff <- structure(
     function(nw, arglist, ..., version=packageVersion("ergm")) {
       ### Check the network and arguments to make sure they are appropriate.
       a <- check.ErgmTerm(nw, arglist, directed=NULL, bipartite=NULL,
                           varnames = c("attr","pow"),
                           vartypes = c(ERGM_VATTR_SPEC,"numeric"),
                           defaultvalues = list(NULL,1),
                           required = c(TRUE,FALSE))
       ### Process the arguments
       nodecov <- ergm_get_vattr(a$attr, nw, accept="numeric")
       covname <- attr(nodecov, "name")
       ### Construct the list to return
       list(name="absdiff",                                     #name: required
            coef.names = paste(paste("absdiff",if(a$pow!=1) a$pow else "",sep=""), covname, sep="."), #coef.names: required
            inputs = c(a$pow,nodecov),  # We need to include the nodal covariate for this term
            dependence = FALSE # So we don't use MCMC if not necessary
            )
     },
     args = alist(attr, pow=1),
     keywords = c("binary", "dyad-independent", "frequently-used", "directed", "undirected", "quantitative nodal attribute"),
     title = "Absolute difference",
     description = "The \\code{attr} argument specifies a quantitative attribute (see \\NodalAttr for details). This term adds one network statistic to the model equaling the sum of \\code{abs(attr[i]-attr[j])^pow} for all edges (i,j)  in the network.")

2. A helper function (e.g., .gen_term_docs()) scans through the namespaces of loaded packages and generates Rd code for their list, sorted and sectioned as needed based on the attributes.
3. The ergm-terms.Rd calls \Sexpr[stage=render,results=rd]{.gen_term_docs()}.

I see the following upsides and downsides relative to the Roxygen approach:

• Does not require learning the Roxygen extension API.
• Should be able to generate term documentation dynamically, with entries added as new packages are loaded.
  • Though it should be possible to generate aliases (i.e., so that ?absdiff brings up the help for the terms), I suspect that that can only be done at the build or the installation stage, which means that those can't be dynamically updated.
• Does require writing raw Rd (rather than Markdown) code. (It may be worth seeing if Roxygen exports the function it uses to convert Markdown to Rd.)
• Less amenable to other preprocessing, such as being able to create a separate help file for each term, as opposed to a wall of text.
  • Code in .gen_term_docs() could be run before build as a poor man's Roxygen, however.

@martinamorris , @mbojan , @chad-klumb , @drh20drh20 , @sgoodreau , @CarterButts , @handcock , any thoughts?

[krivit]

For comparison, I imagine documentation for customised Roxygen would look something like this:

#' @docType ergmTerm
#' @usage absdiff(attr, pow=1)
#' @title Absolute difference
#' @details The \code{attr} argument specifies a quantitative attribute (see \NodalAttr for details). This term adds one network statistic to the model equaling the sum of \code{abs(attr[i]-attr[j])^pow} for all edges (i,j)  in the network.
#' @keywords binary, dyad-independent, frequently-used, directed, undirected, quantitative nodal attribute
InitErgmTerm.absdiff <- function(nw, arglist, ..., version=packageVersion("ergm")) {
  ETC...
}

[mbojan]

I think I Iike Roxygen more than the idea from #28 (comment). I think we can use @family for all the tagging/grouping. What would we need the custom Roxygen API for?

Is the idea to still have all the terms documented on a single page, grouped somehow or each one having its own?

I'm not a big fan of the current setup with one big page because its cumbersome to scroll/search through.

[krivit]

Roxygen API is designed for documenting functions, and it wouldn't know what to do with InitErgmTerm.*() functions.

I am having trouble envisioning how to use Roxygen here without extensions. Can I ask you to prototype it for 2-3 terms (e.g., edges and absdiff) in a branch?

[mbojan]

Sure, I'll have a look.

Are we aiming at one big page or separate ones with lots of interlinks?

[krivit]

I was thinking either one big page or both. (Alternatively, the one big page could be an index page with brief term descriptions linking to separate ones.)

[mbojan]

Or one big vignette and separate Rd files?