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:
Related
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.
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've developed a R package but for some reason the dataset that goes with the package is not being loaded properly when the package is Roxygenised and installed. I have a .R script in the R folder of the package that looks like this
#' Score Card
#' #docType data
#' #name scoreCard
#' #aliases scoreCard
#' #format An object of class \code{data.frame} with 119 rows and 3 columns.
#' \describe{
#' \item{Category}{The Category for which an observation is made}
#' \item{Observation}{The possible responses given for each category}
#' \item{Score}{The score allocated against a response for each category}
#' }
#' #source Internal
#' #usage scoreCard
#' #keywords datasets
NULL
This creates an .Rmd file for the dataset when Roxygenise is called but when I try to call the data set using packageName::scoreCard it states 'scoreCard' is not an exported object from 'namespace:packageName'. Can anyone spot what I might have done wrong in the above script or any other ideas of what might be going wrong, I'm at a bit of a loss? (The data set is stored in the data folder of the package as per normal.) Afraid I can't share the data or package sorry.
Right I didn't realise I needed LazyData: true in my description file. Should have read this more carefully: http://r-pkgs.had.co.nz/data.html
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.
I am new to roxygen and am struggling to see how to be able to use it to quickly create a new/custom package.
I.e. I would like to know the minimum requirements are to make a package called package1 using devtools, roxygen2/3 so that I can run the commands
require(package1)
fun1(20)
fun2(20)
to generate 2000 and 4000 random normals respectively
So lets take the simplest example.
If I have two functions fun1 and fun2
fun1 <- function(x){
rnorm(100*x)
}
and
fun2 <- function(y){
rnorm(200*y)
}
the params are numeric, the return values are numeric. I'm pretty sure this isn't an S3 method, lets call the titles fun1 and fun2....im not too sure what other info i would need to provide. I can put fun1 and fun2 in separate .R files and add abit of #' but am unsure to include all relevant requirements for roxygen and also am unsure what to include as relevant requiremetns and how to use it to create the rd documentation to go with a package are. I presume the namespace would just have the names fun1 and fun2? and the package description would just be some generic information relating to me...and the function of the package?
any step by step guides would be gladly received.
EDIT: The below is how far I got to start with...
I can get as far as the following to create a pacakge...but cant use roxygen to make the documentation...
package.skeleton(list = c("fun1","fun2"), name = "package1")
and here is where I am not sure if I am missing a bunch of steps or not...
roxygenise("package1")
so when trying to install i get the following error message
system("R CMD INSTALL package1")
* installing to library ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library’
* installing *source* package ‘package1’ ...
** R
** preparing package for lazy loading
** help
Warning: /path.to.package/package1/man/package1-package.Rd:32: All text must be in a section
*** installing help indices
Error in Rd_info(db[[i]]) :
missing/empty \title field in '/path.to.package/package1/man/fun1.Rd'
Rd files must have a non-empty \title.
See chapter 'Writing R documentation' in manual 'Writing R Extensions'.
* removing ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library/package1’
I'm surprised #hadley says to not use package.skeleton in his comment. I would use package.skeleton, add roxygen comment blocks, then delete all the files in the "man" directory and run roxygenize. However, since Hadley says "Noooooooooo", here's the minimum you need to be able to build a package that passes R CMD check and exports your functions.
Create directory called "package1". Under that directory, create a file called DESCRIPTION and put this in it (edit it appropriately if you like):
DESCRIPTION
Package: package1
Type: Package
Title: What the package does (short line)
Version: 0.0.1
Date: 2012-11-12
Author: Who wrote it
Maintainer: Who to complain to <yourfault#somewhere.net>
Description: More about what it does (maybe more than one line)
License: GPL
Now create a directory called "R" and add a file for each function (or, you can put both of your functions in the same file if you want). I created 2 files: fun1.R and fun2.R
fun1.R
#' fun1
#' #param x numeric
#' #export
fun1 <- function(x){
rnorm(100*x)
}
fun2.R
#' fun2
#' #param y numeric
#' #export
fun2 <- function(y){
rnorm(200*y)
}
Now you can roxygenize your package
R> library(roxygen2)
Loading required package: digest
R> list.files()
[1] "package1"
R> roxygenize("package1")
Updating collate directive in /home/garrett/tmp/package1/DESCRIPTION
Updating namespace directives
Writing fun1.Rd
Writing fun2.Rd
Since you mentioned devtools in the title of your Q, you could use the build and install functions from devtools
build('package1')
install('package1')
Or you can exit R and use the tools that come with R to build/check/install.
$ R CMD build package1
$ R CMD check package1_0.0.1.tar.gz
$ R CMD INSTALL package1_0.0.1.tar.gz
Now, fire up R again to use your new package.
$ R --vanilla -q
library(package1)
fun1(20)
fun2(20)
But, figuring out the minimum requirements is unlikely to help you (or the users of your package) much. You'd be much better off studying one of the many, many packages that use roxgen2.
Here's a better version of the fun1.R file which still doesn't use all the roxygen tags that it could, but is much better than the bare minimum
Modified fun1.R
#' fun1
#'
#' This is the Description section
#'
#' This is the Details section
#'
#' #param x numeric. this is multiplied by 100 to determine the length of the returned vector
#' #return a numeric vector of random deviates of length \code{100 * x}
#' #author your name
#' #seealso \code{\link{fun2}}
#' #examples
#' fun1(2)
#' length(fun1(20))
#' #export
fun1 <- function(x){
rnorm(100*x)
}
Much later - You could let RoxygenReady prepare your functions with the minimal Roxygen annotation skeleton. It basically brings you from your 2 input functions to GSee's answer, which is the input of Roxygen2.