Closed yongrenjie closed 8 months ago
I think we should avoid editing the roxygen files by hand if we can.
Yup, you're absolutely right! Those files should only be edited by running e.g. devtools::document()
.
I think the really ideal case would be to gitignore files like NAMESPACE
and make the user regenerate it when they clone the repo. The issue with this I think is when we submit to CRAN (and we plan to, right?) those files have to be present for the package to build, so we have to keep them there :x.
We should also think about how to deal with the global variables for the seed. At the moment I think they’re defined in a couple of files (this is my fault) but we should have it somewhere central, obvious and accessible. I don’t think the primary workflow should require random numbers in it, but I think it would be good to make sure it doesn’t/ensure there are no side effects.
I think we can use a function parameter with a default argument. Agreed that it shouldn't need random numbers, I think it's only the data generation bit that uses that.
Do we want to save the “tmp” files in the repo? the fst and the zsav ones?
I'd say not, I gitignore'd them to be safe too.
We should be consistent with naming RE snake_case etc.
Sure! Let's snake_case everything. 🐍
This PR:
Sets up HTML documentation generation with pkgdown (see: https://pkgdown.r-lib.org/ and
vignette('customise')
). Instructions on building are inminisparra/README.md
Adds roxygen comments in
R/miniSPARRA01-package.R
so thatdplyr
and the%>%
operator are visible across the entire package.Sets up a GitHub Actions workflow which builds both the library documentation, renders the Quarto pages, and deploys both to GitHub Pages. See: https://alan-turing-institute.github.io/SPARRA/docs/ and https://alan-turing-institute.github.io/SPARRA/quarto/
Some notes to check back against, because R packaging is really quite different from what I'm used to:
library(...)
in library code. Instead list imports in theDESCRIPTION
file.Imports:
section of theDESCRIPTION
file. So, if theImports:
section listsdplyr
, then we can usedplyr::mutate()
anywhere in the package.NAMESPACE
file controls whether functions need to be prefixed with package names. For example, just listingdplyr
in theDESCRIPTION
file allows us to use any function fromdplyr
but they must be prefixed withdplyr::
. If theNAMESPACE
file contains a line sayingimport(dplyr)
(as it does now), then we can drop thedplyr::
prefix. Alternatively, if it contains a line sayingimportFrom(dplyr, mutate)
then we can just writemutate()
, but any other functions fromdplyr
must still be prefixed.devtools::document()
ordevtools::check()
.) Roxygen uses special comments (beginning with#'
) to determine what to put in this file. A comment like#' @import dplyr
will generate a line inNAMESPACE
withimport(dplyr)
..R
files, unlike in (say) Python, where each file has its own import statements.{packageName}-package.R
. This file can be set up using, for example,[usethis::use_package_doc()](https://usethis.r-lib.org/reference/use_package_doc.html)
, or manually.NULL
below the comments. However, in this case we can use the special string"_PACKAGE"
. Any comments above this will be transformed into documentation associated with the package itself, so this is a good place to put overall info about a package.