“srr” stands for Software Review Roclets, and is rOpenSci’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. Before proceeding, the answer to an important question: What is a “roclet”?
roxygen2 package to
convert roxygen2-style
documentation lines into some desired form of output.This package currently serves to aid developers and reviewers of statistical software in aligning their software against our extensive lists of standards. In acknowledgement of Colin Gillespie’s sentiments expressed in his keynote speech at the European R Users Meeting 2020:
Standards are good
Standards should be strict
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.
The roxygen2
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 package
includes roclets to process a number of tags; the srr
package implements custom roclets to process several additional tags for
use with rOpenSci’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. The functions are mostly intended to ease alignment and assessment of software against the standards detailed in the main project book (from here on referred to as the “SSR Book”).
The easiest way to install this package is via the associated r-universe.
As shown there, simply enable the universe with
options (repos = c (
ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
CRAN = "https://cloud.r-project.org"
))And then install the usual way with,
install.packages ("srr")Alternatively, the package can be installed by running one of the following lines:
remotes::install_github ("ropensci-review-tools/srr")
pak::pkg_install ("ropensci-review-tools/srr")
remotes::install_git ("https://codeberg.org/ropensci-review-tools/srr")
remotes::install_git ("https://codefloe.com/ropensci-review-tools/srr")and loaded for use with,
library (srr)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,
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.
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”.
The third of the following steps describes how to link your package with
srr in order to use these roclets.
Ensure that your package successfully passes all 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.
Decide which of our in-scope categories of statistical software
best describe your package. The function srr_stats_categories()
provides a list of currently developed categories for which standards
have been developed, along with links to the online standards for each
category:
srr_stats_categories ()$title## [1] "General"
## [2] "Bayesian"
## [3] "EDA"
## [4] "Machine Learning"
## [5] "Regression and Supervised Learning"
## [6] "Spatial"
## [7] "Time Series"
## [8] "Dimensionality Reduction, Clustering, and Unsupervised Learning"
## [9] "Probability Distributions"That function also returns links to the full descriptions of each category in the main project book. Any software within one or more of these categories may be considered for review.
Enable your package to use the srr_stats roclets by
modifying the package’s DESCRIPTION file so that the
Roxygen line looks like this:
Roxygen:list (markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))That will load the “roclet”
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.
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>")).
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:
## [1] "#' srr_stats"
## [2] "#'"
## [3] "#' All of the following standards initially have `@srrstatsTODO` tags."
## [4] "#' These may be moved at any time to any other locations in your code."
## [5] "#' Once addressed, please modify the tag from `@srrstatsTODO` to `@srrstats`,"
## [6] "#' or `@srrstatsNA`, ensuring that references to every one of the following"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
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 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.
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 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.
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()
function. Any non-applicable standards can then just be moved into this
block, with their @srrstatsTODO tags changed to
@srrstatsNA
Each time you run devtools::document()
or the equivalent roxygen2::roxygenise(),
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, 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(),
which will generate a skeleton of a package with several roxygen2 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:
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().
Running a second time will generate cleaner output from the
srr_stats roclets only. The tags included in roxygen2 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 lines and
run roxygensise()
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.
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’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.
Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
All contributions to this project are gratefully acknowledged using
the allcontributors
package following the allcontributors specification.
Contributions of any kind are welcome!
mpadge |
maelle |
christophsax |
santikka |
schneiderpy |
abigailkeller |
noamross |
jeroen |
s3alfisc |