-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
361 lines (303 loc) · 15.9 KB
/
README.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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
---
title: "srr"
output:
md_document:
variant: gfm
rmarkdown::html_vignette:
self_contained: no
---
<!-- badges: start -->
[](https://github.com/ropensci-review-tools/srr/actions)
[](https://codecov.io/gh/ropensci-review-tools/srr)
[](https://www.repostatus.org/#concept)
<!-- badges: end -->
<!-- README.md is generated from README.Rmd. Please edit that file -->
# srr
"srr" stands for **S**oftware **R**eview **R**oclets, and is
[rOpenSci](https://ropensci.org)'s package for extending documentation to
include additional components specific to the software review process. The
package currently facilitates documenting how statistical software complies
with our collections of [Statistical Software
Standards](https://stats-devguide.ropensci.org/standards.html). Before
proceeding, the answer to an important question: **[What is
a "roclet"](https://github.com/r-lib/roxygen2/issues/1086)?**
- A roclet is an object used by the [`roxygen2`](https://roxygen2.r-lib.org)
package to convert [`roxygen2`](https://roxygen2.r-lib.org)-style
documentation lines into some desired form of output.
## Why then?
This package currently serves to aid developers and reviewers of statistical
software in aligning their software against our extensive [lists of
standards](https://stats-devguide.ropensci.org/standards.html).
In acknowledgement of [Colin Gillespie](https://github.com/csgillespie)'s
sentiments expressed in his keynote speech at the [European R Users Meeting
2020](https://2020.erum.io/program/keynotes-invited-speakers/):
> Standards are good<br>
> Standards should be strict<br>
> No-one reads standards
the `srr` package aims to integrate the task of aligning software with
standards within the practice of coding itself, and to make standards adherence
as painless as possible.
## How?
The [`roxygen2`](https://roxygen2.r-lib.org) package parses all documentation
lines from all files in the `R/` directory of a package which begin with `#'`.
Special tags beginning with `@`, such as `@param` or `@export`, may follow
these symbols, and roclets define what is done with different kinds of tags.
The [`roxygen2`](https://roxygen2.r-lib.org) package includes roclets to
process a number of tags; the `srr` package implements custom roclets to
process several additional tags for use with [rOpenSci](https://ropensci.org)'s
software review systems, and to process tags in locations other than just the
`R/` directory.
At present, the package only contains roclets and associated functions to help
those developing and reviewing packages submitted to rOpenSci's system for
[Statistical Software
Review](https://stats-devguide.ropensci.org/).
The functions are mostly intended to ease alignment and assessment of software
against the standards detailed in the [main project
book](https://stats-devguide.ropensci.org/standards.html)
(from here on referred to as the "SSR Book").
## Installation
The easiest way to install this package is via the associated
[`r-universe`](https://ropensci-review-tools.r-universe.dev/ui#builds). As
shown there, simply enable the universe with
```{r options, eval = FALSE}
options (repos = c (
ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
CRAN = "https://cloud.r-project.org"
))
```
And then install the usual way with,
```{r install, eval = FALSE}
install.packages ("srr")
```
Alternatively, the package can be installed by running one of the following
lines:
```{r remotes, eval = FALSE}
remotes::install_github ("ropensci-review-tools/srr")
pak::pkg_install ("ropensci-review-tools/srr")
```
and loaded for use with,
```{r lib-fakey, eval = FALSE}
library (srr)
```
```{r lib, echo = FALSE, message = FALSE}
devtools::load_all (".", export_all = FALSE)
```
## Overview
Both this `README`, and the main package vignette, describe the functionality
of the package in the specific context of the statistical software review
project. Both the roclet and all functions intended for use in this context are
prefixed with `srr_stats_`. The remainder of this document is in two main
sections. If you're developing a statistics package for submission to our peer
review system, keep straight on reading. If you've been invited to review a
package, you may skip the following section and just read the subsequent
section. The general procedures for both developers and reviewers are described
at length in the [SSR
book](https://stats-devguide.ropensci.org/standards.html),
with this `README` intended to provide supporting technical details.
Note that the `srr` package can be applied only within the working directory of
a package. There are no `package` or `path` arguments to allow functions to be
applied to packages anywhere other than in the current working directory.
## For Package Developers
People intending to develop packages for submission to our system for peer
reviewing statistical software will need to follow the following general steps.
Note that, while the `srr` package has a few functions which developers may
call directly to aid their submission process, most functionality of this
package is implemented via custom [`roxygen2`
"roclets"](https://roxygen2.r-lib.org). The third of the following steps
describes how to link your package with `srr` in order to use these roclets.
1. Ensure that your package successfully passes all
[`autotest`](https://github.com/ropensci-review-tools/autotest) tests, potentially
including setting `test = FALSE` flags to switch off any tests you consider
not to be applicable to your package. For details, please see the [package
documentation for `autotest`](https://docs.ropensci.org/autotest/).
2. Decide which of our in-scope categories of statistical software best
describe your package. The function
[`srr_stats_categories()`](https://docs.ropensci.org/srr/reference/srr_stats_categories.html)
provides a list of currently developed categories for which standards
have been developed, along with links to the online standards for each
category:
```{r available}
srr_stats_categories ()$title
```
That function also returns links to the full descriptions of each category
in the [main project
book](https://stats-devguide.ropensci.org/standards.html).
Any software within one or more of these categories may be considered for
review.
3. Enable your package to use the `srr_stats` roclets by modifying the
package's `DESCRIPTION` file so that the `Roxygen` line looks like this:
```{r roxygen, eval = FALSE}
Roxygen:list (markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))
```
That will load the ["roclet"](https://roxygen2.r-lib.org) used by this
package to process the documentation of statistical standards within your
actual code. Note that you do not need to add, import, or depend upon the
`srr` package anywhere else within the `DESCRIPTION` file or your actual
package.
4. Load the `srr` package and generate lists of standards within your
package's `/R` folder by running,
[`srr_stats_roxygen(category = c("<my-category-1>", "<my-category-2>"))`](https://docs.ropensci.org/srr/reference/srr_stats_roxygen.html).
This will by default create a new file called by default
`R/srr_stats_standards.R`, the first few lines of which will look like this:
```{r srr_stats_roxygen, echo = FALSE, message = FALSE}
f <- "./R/srr-stats-standards.R"
if (!file.exists (f)) {
srr_stats_roxygen ()
}
rso <- readLines (f)
head (rso)
```
The file will contain a list of all standards from your nominated
categories. This file may be renamed, and the individual items moved to
other locations in other files, but all nominated standards should remain
in [`roxygen2`](https://roxygen2.r-lib.org) blocks somewhere in your source
code.
The `@srrstatsVerbose` line defines a variable which may be used to
suppress output from the `srrstats` roclet when updating package
documentation (by setting to `FALSE`). After that comes the list of
standards, each of which is prefixed by
a [`roxygen2`](https://roxygen2.r-lib.org) tag, `@srrstatsTODO`. A package
can only be submitted once all of these `TODO` items have been addressed
via one of the options described in the following two items.
5. A standard may be addressed by moving the item in the
`srr-stats-standards.R` file (or wherever you've chosen to list these within
your own package) to one or more places in your code where these standards
have been addressed. In doing so, the
[`roxygen2`](https://roxygen2.r-lib.org) tag should be changed from
`@srrstatsTODO` to `@srrstats`, and the text which initially lists the
actual standard should be changed to provide a brief description of how that
standard has been met. Tags for one particular standard may be repeated in
multiple places within your code, and we encourage locating multiple
`@srrstats` tags which refer to a particular standard at all locations which
directly address that standard.
6. Alternatively, any standards which you consider not applicable to your
software may remain listed in the templated section of the main
`srr-stats-standards.R` document (or any alternative location), with their
tag changed from `@srrstatsTODO` to `@srrstatsNA`, and the description of
the standard removed and replaced by an explanation of why you consider that
standard not to be applicable to your software. These `@srrstatsNA` tags
should be collected together within a single `roxygen2` block with a title
of `NA_standards`, as provided in the initial template generated by the
[`srr_stats_roxygen()`](https://docs.ropensci.org/srr/reference/srr_stats_roxygen.html)
function. Any non-applicable standards can then just be moved into this
block, with their `@srrstatsTODO` tags changed to `@srrstatsNA`
7. Each time you run
[`devtools::document()`](https://devtools.r-lib.org/reference/document.html)
or the equivalent
[`roxygen2::roxygenise()`](https://roxygen2.r-lib.org/reference/roxygenize.html),
the roclet will scan your package's documentation for the state of
standards, and will generate a summary of the result on your screen. Note,
however, that the `roxygen2` package [only scans files in the R
directory](https://github.com/r-lib/roxygen2/blob/9652d15221109917d46768e836eaf55e33c21633/R/package_files.R#L1-L10),
and so this screen output will only summarise standards documented there.
Standards documented in other locations such as test files or vignettes
will be recognised and processed by the `srr` package, even through they
will not be recognised by the `document()/roxygenise()` functions, and so
will not appear in their output.
To help developers understand how to use these roclets, this package includes a
function,
[`srr_stats_pkg_skeleton()`](https://docs.ropensci.org/srr/reference/srr_stats_pkg_skeleton.html),
which will generate a skeleton of a package with several
[`roxygen2`](https://roxygen2.r-lib.org) tags inserted throughout the code.
This function returns the directory where the skeleton package has been
created, so running the following two lines will illustrate the roclets in
action:
```{r demo, eval = FALSE}
d <- srr_stats_pkg_skeleton ()
roxygen2::roxygenise (d)
```
Note that the skeleton package also includes C++ code in a `src/` directory, so
will be compiled the first time your run
[`roxygensise()`](https://roxygen2.r-lib.org/reference/roxygenize.html).
Running a second time will generate cleaner output from the `srr_stats` roclets
only. The tags included in
[`roxygen2`](https://roxygen2.r-lib.org/) blocks in this skeleton package may
be modified, moved, copied, and changed in any way you like to help you
understand how the roclets work. Simply play around with the
[`roxygen2`](https://roxygen2.r-lib.org/) lines and run
[`roxygensise()`](https://roxygen2.r-lib.org/reference/roxygenize.html) each
time to see the effect. Individual standards may be moved to, and addressed in,
any location including the directories `R/`, `src/`, or `tests/`, and well as
in `.Rmd` documentation files such as `README.Rmd` or package vignettes. The
`srr_stats` roclet associated with this package is able to parse the various
`@srrstats` tags in all of these locations.
### Places where standards can NOT be inserted
While the `srr` package enables standards compliance to be documented through
inserting `@srrstats` tags in as many locations as possible, in order to ensure
compliance is documented as close as possible to the point within the code
where each standard is addressed, it is not possible to insert `roxygen2` tags
in every type of file. In general, standards may be inserted in any `.R` or
`.Rmd` file, and most types of files in `src` or `inst/include` directories, as
long as they are used with a package able to convert documentation to
a corresponding R file (such as [`Rcpp`](http://www.rcpp.org/)'s generation of
`RcppExports.R` files which include the C++ documentation).
Tags may generally not be placed in any other kinds of files, including `.md`
files such as `CONTRIBUTING.md`, or other files without extensions such as
`DESCRIPTION`, `NAMESPACE`, or `NEWS`. Standards which are best addressed in
such files must be placed in some other generic location (such as
`R/srr-standards.R`), with a cross-reference to the file in which they are
actually addressed.
## Code of Conduct
Please note that this package is released with a [Contributor Code of
Conduct](https://ropensci.org/code-of-conduct/). By contributing to this
project, you agree to abide by its terms.
## Contributors
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropenscilabs/allcontributors) following the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome!
### Code
<table>
<tr>
<td align="center">
<a href="https://github.com/mpadge">
<img src="https://avatars.githubusercontent.com/u/6697851?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci-review-tools/srr/commits?author=mpadge">mpadge</a>
</td>
<td align="center">
<a href="https://github.com/christophsax">
<img src="https://avatars.githubusercontent.com/u/1390827?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci-review-tools/srr/commits?author=christophsax">christophsax</a>
</td>
<td align="center">
<a href="https://github.com/maelle">
<img src="https://avatars.githubusercontent.com/u/8360597?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci-review-tools/srr/commits?author=maelle">maelle</a>
</td>
</tr>
</table>
### Issue Authors
<table>
<tr>
<td align="center">
<a href="https://github.com/santikka">
<img src="https://avatars.githubusercontent.com/u/8639149?v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci-review-tools/srr/issues?q=is%3Aissue+author%3Asantikka">santikka</a>
</td>
<td align="center">
<a href="https://github.com/schneiderpy">
<img src="https://avatars.githubusercontent.com/u/77991319?u=4242d4c5942fced6368dd5c68221e6618092cbf8&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci-review-tools/srr/issues?q=is%3Aissue+author%3Aschneiderpy">schneiderpy</a>
</td>
</tr>
</table>
### Issue Contributors
<table>
<tr>
<td align="center">
<a href="https://github.com/jeroen">
<img src="https://avatars.githubusercontent.com/u/216319?u=bfe086cade8ccec09d43f3f2e1bb3b6304dc7ec6&v=4" width="100px;" alt=""/>
</a><br>
<a href="https://github.com/ropensci-review-tools/srr/issues?q=is%3Aissue+commenter%3Ajeroen">jeroen</a>
</td>
</tr>
</table>
<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->