The help() function allows us to see an index with a list of all functions within a package:
help(package=stats)
If the package is very large, the help page will be automatically broken down alphabetically, with links to each section by initial letter (as in the case of stats). Smaller packages will have all the functions together in alphabetical order.
Is this index page customizable?
I'm using roxygen2, and would love to be able to group functions by their #family.
See section 10.6 of R Packages :
You can use roxygen to provide a help page for your package as a whole.
you need to document NULL, and then manually label it with #docType package and #name . This is also an excellent place to use the #section tag to divide up page into useful categories.
Just create an mypackage.R file with the above Roxygen tags applied to NULL:
#' Mypackage: A package I created
#'
#' MyPackage has different families of functions described below
#'
#' #section Some functions:
#' * [mysum()]
#' * [myprod()]
#'
#' #section Other functions:
#' * [other()]
#' * [foo()]
#'
#' #docType package
#' #name mypackage
NULL
The brackets [] allow to create links to the functions of the package.
Related
I'm putting some R code together in a package, and struggling with namespace + import/export problems. It seems that whether or not I add an #' #export line in roxygen, the functions are still visible to the user. So if I have this file:
#' Function I want the user to see
#'
#' A description
#'
#' #param X a parameter
#' #return the same thing
#' #export
external_function<-function(X){X}
#' Function I don't want the user to see
#'
#' A description
#'
#' #param X a parameter
#' #return the same thing
internal_function<-function(X){X}
both functions end up being exposed, along with library.dynam.unload and system.file:
It doesn't seem to make any difference whether the functions are in separate files or not - even if all the functions that shouldn't be exposed are in one file, without any that should, they're still appearing.
Relatedly, all functions from other packages which I import are appearing - I don't know whether this is intended behaviour (it certainly isn't what I wanted!) or whether this is part of the same issue.
#' Function I want the user to see
#'
#' A description
#'
#' #param X a parameter
#' #return the same thing
#' #importFrom dplyr %>%
#' #export
external_function<-function(X){X %>% log}
with this line in the DESCRIPTION file:
Imports:
dplyr
results in:
What am I doing wrong? Is there a way to use functions internally without them being exposed to the user?
The problem was with the way I'd loaded the package, using devtools::load_all(). Using devtools::load_all(...,export_all=F) or loading the package without devtools means that only the right functions are exported :).
How do I make devtools::build_manual put package documentation on the first page of the manual?
#' flowNet: Mapping the Topology of Single Cell Data
#'
#' Some text...
#'
#' #section Some more text...
#'
#' #docType package
#' #name flowNet
NULL
#> NULL
.datatable.aware <- TRUE
Output:
I do not think you can, and you have your tools crossed. devtools does not influence how base R collates all Rd entries into a pdf.
But I just took one guess at an older package (xts) by a friend and indeed, it has a first entry ending in "-package":
So just add an entry flowNew-package (via roxygen2) and you should be good.
Here is another example from a package of mine:
I'm writing an R package, and I'd like to include cross references between function documentation.
Following the documentation here, there's a setion that talks specifically about this:
Cross-references
There are two tags that make it easier for people to navigate around your documentation: #seealso and #family. [...] If you have a family of related functions, you can use #family {family} to cross-reference each function to every other function within the family. A function can be a member of multiple families.
For sum(), this might look like:
#' #family aggregations
#' #seealso [prod()] for products, [cumsum()] for cumulative sums, and
#' [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.
By default #family {family}, will generate the see also text “Other {family}:”, so the #family name should be plural (i.e., “model building helpers” not “model building helper”). You can override the default title by providing a rd_family_title list in man/roxygen/meta.R:
rd_family_title <- list(
aggregations = "Aggregation functions"
)
So, I've written the documentation of my functions like this:
#' My foo function
#'
#' Does something with my data.
#'
#' Lorem ipsum.
#'
#' #param .data A data frame.
#' #return My processed data.
#' #usage
#' my_foo_function(.data)
#' #family {a_family}
#' #family {another_family}
#' #export
my_foo_function <- function(.data) {
# Some code
}
(there are about 9 functions I've written this way)
I've also written this meta.R file:
rd_family_title <- list(
a_family = "A family of functions",
another_family = "Another family of functions"
)
This is saved here: [package project path]/roxygen/man/meta.R (again, following the documentation).
However, when I run the document() function (to build the .Rd files), I get the following warnings:
document()
## Updating my_package documentation
## Writing NAMESPACE
## Warning messages:
## 1: Unknown Roxygen options a_family, another_family.
## Supported options: roclets, load, old_usage, markdown, r6, package
And, when browsing the documentation, I see something like this:
[...]
See also
Other a_family: bar(), baz()
Other another_family: spam(), eggs()
(I've changed #family {a_family} with #family a_family and I get the same result.
So... What am I missing? Where should the rd_family_title list be? Why is Roxygen failing to replace that "other..." stuff with the titles I've defined?
Some aditional info:
R version: 3.6.0, running on CentOs 7, and using Rstudio
Roxygen2 version: 7.0.2
devtools version: 2.2.1
This has been fixed in PR 1078 which is included in the roxygen2 7.1.1 release.
I'm writing an R package and largely following Hadley's book on the topic. I'm running into a problem with documenting methods for simple generics like print, plot, head, and tail. When I use the #describeIn tag to control where the method documentation goes, I get the nice feature of them showing up in the help file for the main analysis function that returns an object of the given class. The problem is that these generics also show up in the package's index. If I add #keywords internal to the generics, then they are removed from the package's index, but so is the main analysis function (they are in the same .R file). If I document the generics in a separate .R file, then I can gain control over what is and is not in the package's index, but I have two issues: the main analysis function doesn't come first in the Usage section of the help file; and if add the #keywords internal for the generics, this removes the analysis function from the package index too, even though they are documented (in this instance) in separate files. The crux of the problem seems to be that #keywords internal applies to all functions in the given .R file, and maybe even any function referenced in #describeIn, while #describeIn is designed for documenting multiple functions in a given .R file.
For now, I have the analysis function and generics in the same .R file to control where the method documention goes and its ordering in the Usage section, but am not using #keywords internal and leaving the index cluttered.
Here's a rough sketch of an exported analysis function:
#' #inheritParams foo
#' #export
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
And a generic:
#' #describeIn seats Print a \code{\link{seats}} output
#' #keywords internal
#' #export
print.judgeit.seats <- function(x,...) print(x$output,...)
I want the help file for ?seats to look like this:
seats(judgeit.object, ...)
## S3 method for class 'judgeit.seats'
print(x, ...)
## S3 method for class 'judgeit.seats'
head(x, ...)
## S3 method for class 'judgeit.seats'
tail(x, ...)
I do not want print.judgeit.seats, head.judgeit.seats, etc. to appear in the package index, because it quickly becomes very cluttered.
Unfortunately, I am not aware of any easy fix for what you are asking.
Tags and their effect
#export will make your function visible in the global environment. CRAN requires that you document any such functions that is not hidden (i.e. that starts with .).
If you use #describeIn or #rdname, an automatic alias is created. Any alias creates an entry in the index, but points to the same .Rd file. For example, adding
#' #name myfunction
#' #aliases foo foobar`
would create foo and foobar entries in the index, but refer to the myfunction.Rd documentation file. If you try to delete manually the \alias{} in the .Rd file, CRAN will complain.
#describeIn will list the functions in the order they appear in the .R files (if they are documented in multiple files, they are listed according to the alphabetical order of the .R file, then the order of appearance). Reordering your functions can give you what you want.
#keywords internal (along with #export, a title and a description) will have Roxygen create a .Rd file that can be accessed by the user using ?, but will not be visible in the index (if you have only the tags, Roxygen will not create a .Rd file and you will get a warning because your function is not documented).
If you have a #keywords internal in any of the functions calling #describeIn, that function will be masked from the index. This does not apply to all functions in a .R file, only those which are aliases.
#usage requires you to have an alias for each method documented. You can try using instead #section Usage:, but note sections are listed in alphabetical order and the spacing will be larger.
Workaround
If you document a NULL function, you can add the #param you want. and include a multiple lines #Section: Usage field to include (manually) the S3 methods with your comments. Give it a name such as #name Seats (it cannot be the name of the function, otherwise you have ?seats pointing to two different files).
Then, document your function seats with a different #name tag and a different title, and use #internal' to hide it from the user. Use \code{\link{seats}}` to refer to that documentation.
#' Seats
#' Description of the function
#' #param judgeit.object object
#' #param x object from seats
#' #param ... additional arguments
#' #name seats
#' #section Usage:
#' \preformatted{seats(judgeit.object, ...)
#' ## S3 method for class 'judgeit.seats'
#' print(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' head(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' tail(x, ...)}
NULL
#' Seats function
#' #name internal-function
#' #inheritParams seats
#' #export
#' #keywords internal
#' #seealso \code{\link{seats}}
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
#' Print a \code{\link{seats}} output
#'
#' #inheritParams seats
#' #describeIn internal-function
#' #export
print.judgeit.seats <- function(x,...) print(x$output,...)
This way, the user calling ?seats will be pointed to the overall documentation.
I am writing an R package and create documentation using roxygen2. I build the package and the documentation using the button Build & Reload in RStudio. According to RStudio's output, it uses devtools::document(roclets=c('rd', 'namespace')) to compile the documentation.
I want to use the #family tag to link together a number of functions in the documentation and this is where my problem occurs. This line
#' #family functions returning some object
is converted in the .Rd file to the following
\seealso{
Other functions.returning.some.object: \code{\link{test2}}
}
I don't want the dots between the words. I have an older package, where this does not happen, even if I recompile the documentation in the exact same setting as I compile the new package. I can see no fundamental difference between this older package and my new attempt.
I have written a very simple test package, where the problem also occurs. It contains a single R file (testpackage.R):
#' Test function 1
#'
#' #param x a number
#'
#' #family functions returning some object
#' #family aggregate functions
#'
#' #export
test1 <- function(x) {
x*x
}
#' Test function 2
#'
#' #param x a number
#'
#' #family functions returning some object
#' #family aggregate functions
#'
#' #export
test2 <- function(x) {
x*x*x
}
The DESCRIPTION file is
Package: testpackage
Type: Package
Title: Package for testing purposes
Version: 1.0
Date: 2015-05-21
Author: Me
Maintainer: Me <me#somewhere.com>
Description: Package for testing purposes
License: GPL-3
NAMESPACE is generated by roxygen. For the documentation test1.Rd, I get:
% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/testpackage.R
\name{test1}
\alias{test1}
\title{Test function 1}
\usage{
test1(x)
}
\arguments{
\item{x}{a number}
}
\description{
Test function 1
}
\seealso{
Other aggregate.functions: \code{\link{test2}}
Other functions.returning.some.object: \code{\link{test2}}
}
with the unwanted dots in the \seealso section. Clearly, the number of words in the #family tag seems not to matter. I have tried enclosing the text in quotation marks, various kinds of brackets, etc. with no positive effect. Of course, I could edit the Rd files, but this would miss the point of using roxygen2.
R CMD check runs without warnings or errors on testpackage.
Why do these dots appear? And how can I get rid of them?
This is a bug in roxygen2 -- I've logged an issue here. It effectively results from the use of unstack(), which performs some unwanted conversions.
I upgraded to Roxygen 5.0.0 (which is now the CRAN version) and found that the problem went away.