-
Notifications
You must be signed in to change notification settings - Fork 0
/
week5-roxygen.Rmd
179 lines (128 loc) · 6.75 KB
/
week5-roxygen.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
---
title: "Week 5: Roxygen"
output:
html_document:
toc: true
include:
after_body: footer.html
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
```{r echo=FALSE, message=FALSE, warning=FALSE}
library(kableExtra)
dt <- data.frame("Compartmentalized", "Documented", "Extendible", "Reproducible", "Robust")
kable(dt, col.names=NULL) %>%
kable_styling(full_width = TRUE) %>%
row_spec(1, bold = FALSE, color = "white", background = "blue") %>%
column_spec(column = 1:5, width = "20%")
```
## Roxygen
We all know that documenting our code is important, but equally important is to be able to read that documentation. If you use R, you know that the help feature (?function) is essential. If you organize your code into an R package, it is super easy to create help files that you and users can use to call up using ?. Documenting code may sound like a snoozer of a topic, but using Roxygen and diligently writing documentation for my functions and data is one of the top 3 habits that has made my coding more efficient. You can also document all your data in the same way.
For more help on Roxygen, see the section in Hadley Wickham's book R Packages on [Documentation](http://r-pkgs.had.co.nz/man.html). Here's a short cheatsheet [Roxygen helper](https://stuff.mit.edu/afs/athena/software/r/current/RStudio/resources/roxygen_help.html). Also Roxygen has good tutorials and help. Type
```
browseVignettes(package="roxygen2")
```
to open a browser window with links to the tutorials.
## Type of documentation
Roxygen (and the the 'Build and Install' step) will create a the help files that users access with `?function.name.
The same man files are also used to create a package manual, e.g.
https://cran.r-project.org/web/packages/MARSS/MARSS.pdf
And it generates the navigation page for all the documentation
```
help(package="forecast")
```
The man files are also used by **pkgdown** to make a website version of your documentation.
Here is an example of the default [pkgdown-generated webpage](http://jebyrnes.github.io/multifunc/index.html).
### Not just for public products!
I use Roxygen to document my personal projects more than for public projects. The Roxygen format helps me document both my functions and data that I am using so that I can reproduce my own work and so I have the information that I need when I do the final write-ups.
## Set-up
### Install the **roxygen2** R package.
```
install.packages("roxygen2")
```
Open your test package, **MyNewPackage**. Open RStudio and then click the little arrow next to the blue cube in the top right corner.
### Set the Project Build Options to use Roxygen
Tools > Project Options... > Build Tools > then check the checkbox "Generate documentation with Roxygen". Then click "Configure". Check the box at the bottom for "Install and Restart".
## Basic structure of Roxygen2 comments
Roxygen comments with #' are put at the top of your function, in the same file. They have a standard format and standard sections. There is a bit of customization you can do, but the following basic form will cover 95% of your needs.
```
#' @title Short title
#'
#' @description
#' Description should be one paragraph. Put details in details.
#'
#' @details
#' Optional if you want to add more detais.J
#'
#' @param param.name1 Describe all your function arguments
#' @param param.name2 Describe all your function arguments
#'
#' @examples
#' # provide some examples of how to use your function
#' hello()
#'
#' @seealso List relevant other functions
#'
#` @references
#' List references
#' @export
yourfunction <- function(param.name1, param.name2){}
```
`@title` and `@description` can be left off (not the text, just the @.... part), but title text should be in line 1, then a blank line (#' only), and then the description text. The only required elements are `@title`, `@description`, and `@param` (defining the function arguments).
`@export` means that your function is added to your NAMESPACE so is not hidden. Just include this for now.
## Add help to `hello()`
First remove the old `hello.Rd` file from the man folder. That is there because when we created our new package using RStudio's template, we didn't select 'use Roxygen' so it added a manually created help (i.e. Rd) file for us in the man folder. Now we are going to use Roxygen, so we need to remove that file.
Copy and paste this to the top of `hello.r` in the R folder. Replace all the comments at the top with these lines.
```
#' Hello World!
#'
#' Prints a the classic first program greeting. It takes no arguments.
#'
#' @examples
#' hello()
#' @export
```
To build the documentation, click 'Install and Restart' from the Build tab.
Once you see that `MyNewPackage` is reloaded (`library(MyNewPackage)` appears on the command line), you can type `?hello` to get the help info.
### The NAMESPACE
Roxygen will complain that the NAMESPACE was not generated by Roxygen so it is ignoring our `@export`. Let delect the NAMESPACE file and try again.
## Updating the documentation
When you update the documentation or add new documentation, rebuild the help files using the 'Install and Restart' button on the Build tab. Note, with the default Project Options, RStudio does not remake the documentation when you click 'Install and Restart'. You have to change that by going to Tools > Project Options > Build Tools and then clicking 'Configure' next to 'Generate documentation with Roxygen' and then clicking the box next to 'Install and Restart'. Or you can run this code to make the documentation.
```
devtools::document()
```
## Customizing your help files
The easiest way to figure out how to customize Roxygen headers is to look at the Roxygen header for a help file you are trying to copy.
### Adding references
If you use BibTex you can insert references by citation in your help files.
1. Create the `inst` folder if you don't have one
2. Within that, create `REFERENCES.bib`
3 Add refs to that in BibTex format.
4. Install the **Rdpack** package
5. Add **Rdpack** to `Imports` in your DESCRIPTION file and add `RdMacros: Rdpack` to your DESCRIPTION file.
3. Cite in your Roxygen header using
```
\insertRef{Waltonetal1998}{MyNewPackage}
```
Example of a reference in `REFERENCES.bib`
```
@article{Waltonetal1998,
title={The development and operational application of nonlinear algorithms for the measurement of sea surface temperatures with the NOAA polar-orbiting environmental satellites},
author={Walton, CC and Pichel, WG and Sapper, JF and May, DA},
journal={Journal of Geophysical Research: Oceans},
volume={103},
number={C12},
pages={27999--28012},
year={1998},
publisher={Wiley Online Library}
}
```
You can get the citation for R packages from
```
citation(package="ggplot2")
```
Add the citation to your Rd file with
```
\insertRef{Waltonetal1998}{MyNewPackage}
```