Package organisation

[yongrenjie]

This PR:

• Sets up HTML documentation generation with pkgdown (see: https://pkgdown.r-lib.org/ and vignette('customise')). Instructions on building are in minisparra/README.md

• Adds roxygen comments in R/miniSPARRA01-package.R so that dplyr and the %>% operator are visible across the entire package.

  • The references I used were: https://roxygen2.r-lib.org/articles/namespace.html and https://r-pkgs.org/man.html#sec-man-package-doc

• 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:

• We shouldn't use library(...) in library code. Instead list imports in the DESCRIPTION file.
• The packages which can be used are controlled by the Imports: section of the DESCRIPTION file. So, if the Imports: section lists dplyr, then we can use dplyr::mutate() anywhere in the package.
• Function visibility is package-wide, not script-local. This is not really ideal but it's an R feature so we have to work with it.
• The NAMESPACE file controls whether functions need to be prefixed with package names. For example, just listing dplyr in the DESCRIPTION file allows us to use any function from dplyr but they must be prefixed with dplyr::. If the NAMESPACE file contains a line saying import(dplyr) (as it does now), then we can drop the dplyr:: prefix. Alternatively, if it contains a line saying importFrom(dplyr, mutate) then we can just write mutate(), but any other functions from dplyr must still be prefixed.
• The NAMESPACE file can be edited by hand, but in our case is automatically generated using Roxygen. (This can be done by running either devtools::document() or devtools::check().) Roxygen uses special comments (beginning with #') to determine what to put in this file. A comment like #' @import dplyr will generate a line in NAMESPACE with import(dplyr).
• Just like the DESCRIPTION file, the NAMESPACE file applies package-wide. So you cannot have different rules for different .R files, unlike in (say) Python, where each file has its own import statements.
• Because of this, the Roxygen-style comments are not located in individual script files but are instead aggregated into a single file, usually called {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.
• The Roxygen-style comments can't just be standalone, they must appear above something which can be documented, such as a function. Some people just put a 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.

[yongrenjie]

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. 🐍