Improve vignettes and docs

R/config-template.R

@@ -168,71 +168,14 @@ generate_cfg_template <- function() {
 #' @export
 #'
 #' @details
-#' The returned keys should be the same as those returned by
-#'   `get_cfg_keys(cfg = generate_cfg_template())`.
+#' The returned keys should be the same as keys in the config that would be
+#'   created with `generate_cfg_template()`.
 #'
 #' @examples
 #' get_cfg_template_keys()
 #'
 get_cfg_template_keys <- function() {
-  sort(c(
-    "run",
-    "run.msoa_lim",
-    "run.seed_val",
-    "store",
-    "store.dat",
-    "store.dat.interim",
-    "store.dat.interim.dirs",
-    "store.dat.interim.dirs.base",
-    "store.dat.interim.fnames",
-    "store.dat.interim.fnames.imputed_tus_dat",
-    "store.dat.raw",
-    "store.dat.raw.dirs",
-    "store.dat.raw.dirs.base",
-    "store.dat.raw.dirs.misc",
-    "store.dat.raw.dirs.population",
-    "store.dat.raw.dirs.shapefiles",
-    "store.dat.raw.dirs.tus",
-    "store.dat.raw.misc",
-    "store.dat.raw.misc.nssec_class",
-    "store.dat.raw.misc.sic2007_class",
-    "store.dat.raw.misc.soc2010_class",
-    "store.dat.raw.nm_patterns",
-    "store.dat.raw.nm_patterns.pop_lad_tus",
-    "store.dat.raw.shapefile_layers",
-    "store.dat.raw.shapefile_layers.ew_msoa",
-    "store.dat.raw.shapefile_layers.uk_full",
-    "store.dat.raw.tus",
-    "store.dat.raw.tus.uk_metadata_location",
-    "store.dat.wrangled",
-    "store.dat.wrangled.dirs",
-    "store.dat.wrangled.dirs.base",
-    "store.dat.wrangled.dirs.population",
-    "store.dat.wrangled.dirs.shapefiles",
-    "store.dat.wrangled.dirs.tus",
-    "store.dat.wrangled.population",
-    "store.dat.wrangled.population_ref",
-    "store.dat.wrangled.population_ref.pop_dat",
-    "store.dat.wrangled.population.pop_dat",
-    "store.dat.wrangled.shapefiles",
-    "store.dat.wrangled.shapefiles_ref",
-    "store.dat.wrangled.shapefiles_ref.msoa",
-    "store.dat.wrangled.shapefiles.ew_msoa",
-    "store.dat.wrangled.shapefiles.ew_msoa_region",
-    "store.dat.wrangled.shapefiles.uk_full",
-    "store.dat.wrangled.time_use_survey",
-    "store.dat.wrangled.time_use_survey_ref",
-    "store.dat.wrangled.time_use_survey_ref.tus_dat",
-    "store.dat.wrangled.time_use_survey.tus_dat",
-    "store.out",
-    "store.out.dirs",
-    "store.out.dirs.activities",
-    "store.out.dirs.base",
-    "store.out.nm_patterns",
-    "store.out.nm_patterns.activities",
-    "store.save",
-    "store.save.imputed_tus_dat"
-  ))
+  get_cfg_keys(cfg = generate_cfg_template())
 }
 
 #' Retrieve the config template file name

R/config-validation.R

@@ -193,7 +193,7 @@ get_invalid_cfg_keys <- function(exp_keys = NULL, cfg_dir = NULL,
   invalid
 }
 
-#' Check if a config has any invalid keys
+#' Check if config has any invalid keys
 #'
 #' @inheritParams ensure_cfg_param_types
 #' @inheritParams get_user_cfg_dir
@@ -204,7 +204,10 @@ get_invalid_cfg_keys <- function(exp_keys = NULL, cfg_dir = NULL,
 #' @export
 #'
 #' @examples
+#' \dontrun{
+#' # Check keys in the default config:
 #' cfg_keys_all_valid()
+#' }
 #'
 cfg_keys_all_valid <- function(exp_keys = NULL, cfg_dir = NULL,
                                cfg_name = NULL, invalid_keys = NULL,
@@ -224,9 +227,9 @@ cfg_keys_all_valid <- function(exp_keys = NULL, cfg_dir = NULL,
   length(invalid_keys) == 0
 }
 
-#' Validate the config
+#' Validate a config
 #'
-#' Check that all entries in the config are valid.
+#' Check that all entries in a config are valid.
 #'
 #' @inheritParams ensure_cfg_param_types
 #' @inheritParams get_user_cfg_dir

R/test-helpers.R

@@ -24,7 +24,7 @@ is_r_cmd_check <- function() {
   nzchar(Sys.getenv("_R_CHECK_PACKAGE_NAME_"))
 }
 
-#' Skip a test on certain conditions
+#' Skip a test under certain conditions
 #'
 #' Skip a test if not running within the context of 'R CMD CHECK'  or not
 #' configured to run, as determined by the value of the supplied system
@@ -163,20 +163,20 @@ get_test_cfg <- function() {
 get_test_cfg_exp_keys <- function() {
   c(
     "top",
-    "top.fruit",
-    "top.fruit.yellow",
-    "top.fruit.red",
-    "top.fruit.green",
     "top.colours",
     "top.colours.main",
     "top.colours.sub",
     "top.colours.sub.sub1",
     "top.colours.sub.sub2",
-    "top.shapes",
-    "top.shapes.oblong",
+    "top.fruit",
+    "top.fruit.green",
+    "top.fruit.red",
+    "top.fruit.yellow",
     "top.locations",
     "top.locations.base_path",
-    "top.locations.other_path"
+    "top.locations.other_path",
+    "top.shapes",
+    "top.shapes.oblong"
   )
 }
 

README.md

@@ -12,7 +12,7 @@ derived from the SPFFinalReport code (created for the case study and
 report for the final SPF reporting period).
 
 <!-- ======================================================================= -->
-<!-- Doc update timestamp: Wed 20 Nov 2024 19:10 GMT -->
+<!-- Doc update timestamp: Thu 21 Nov 2024 13:49 GMT -->
 
 [Browse the source
 code](https://github.com/UoMResearchIT/SPFFinalReport/tree/38-convert-to-r-pkg/)

_pkgdown.yml

@@ -2,7 +2,8 @@ url: https://UoMResearchIT.github.io/SPFFinalReport/
 repo:
   url:
     source: https://github.com/UoMResearchIT/SPFFinalReport/tree/38-convert-to-r-pkg/
-    branch: 38-convert-to-r-pkg
 template:
   bootstrap: 5
   bootswatch: yeti
+deploy:
+  install_metadata: true

inst/pkgdown.yml

@@ -0,0 +1,11 @@
+pandoc: '3.2'
+pkgdown: 2.1.1
+pkgdown_sha: ~
+articles:
+  config: config.html
+  development: development.html
+  dimex: dimex.html
+last_built: 2024-11-21T13:49Z
+urls:
+  reference: https://UoMResearchIT.github.io/SPFFinalReport/reference
+  article: https://UoMResearchIT.github.io/SPFFinalReport/articles

tests/testthat/test-config-template.R

@@ -1,16 +1,9 @@
 # SPDX-FileCopyrightText: [2024] University of Manchester
 # SPDX-License-Identifier: apache-2.0
 
-test_that("config template has valid keys", {
-  exp_keys <- get_cfg_template_keys()
-
+test_that("cfg_keys_all_valid works", {
   cfg_templ <- generate_cfg_template()
-  expect_true(cfg_keys_all_valid(exp_keys = exp_keys, cfg = cfg_templ))
-})
+  exp_keys <- get_cfg_keys(cfg = cfg_templ)
 
-test_that("config template has valid keys", {
-  exp_keys <- get_cfg_template_keys()
-
-  cfg_templ <- generate_cfg_template()
   expect_true(cfg_keys_all_valid(exp_keys = exp_keys, cfg = cfg_templ))
 })

tests/testthat/test-config.R

@@ -24,8 +24,8 @@ test_that("write_user_cfg writes expected config to file", {
 })
 
 test_that("get_cfg_keys works", {
-  exp_keys <- get_cfg_template_keys()
-  expect_equal(get_cfg_keys(cfg = generate_cfg_template()), exp_keys)
+  exp_keys <- get_test_cfg_exp_keys()
+  expect_equal(get_cfg_keys(cfg = get_test_cfg()), exp_keys)
 })
 
 test_that("get_cfg_val fails if keys not found", {

vignettes/config.qmd

@@ -28,20 +28,20 @@ library(dimex)
 ## Background
 
 This vignette describes how to configure the `dimex` package. See
-[introduction to dimex](dimex.html) for context.
+[Get started](dimex.html) for context.
 
 For information about configuration that is relevant within a development
-environment, see [development](development.html).
+environment, see [Development](development.html).
 
 There are two categories of configuration: localised (environment-dependent) and
 default package-level configuration which can be customised to a user's
 circumstances if required.
 
 Environment-dependent configuration values are specified via
-[system environment variables](#sys-env-vars), whilst package-level
-configuration values are specified via the [config](#pkg-config) object.
+[system environment variables](config.html#sys-env-vars), whilst package-level
+configuration values are specified via the [config](config.html#pkg-config) object.
 
-## System Environment Variables for localised configuration {#sys-env-vars}
+## System Environment Variables {#sys-env-vars}
 
 ### `.Renviron` file
 
@@ -103,7 +103,7 @@ effect. This can be achieved by doing one of the following:
 readRenviron("~/.Renviron")
 ```
 
-    (where you shoul replace "~/.Renviron" with the appropriate path to your
+    (where you should replace "~/.Renviron" with the appropriate path to your
     `.Renviron` file if it's not in your home directory)
 
 - A temporary alternative to reloading `.Renviron` is to manually override
@@ -116,7 +116,7 @@ Sys.setenv(VAR_NAME = "value")
     This can be helpful for testing specific changes without modifying the
     environment file.
 
-### Valid system environment variables
+### Valid sys env variables
 
 System environment variables for the `dimex` package start with 'DIMEX_'.
 
@@ -126,10 +126,10 @@ System environment variables for the `dimex` package start with 'DIMEX_'.
 
 | Environment | Variable name   | Description                                        |
 |:------------|:----------------|:---------------------------------------------------|
-| main         | DIMEX_STORE     | Root path of the dimex Data and Output            |
+| main        | DIMEX_STORE     | Root path of the dimex Data and Output             |
 | ref         | DIMEX_STORE_REF | Root path of the dimex 'reference' Data and Output |
 
-## The `config` object for package-level configuration {#pkg-config}
+## The `config` object {#pkg-config}
 
 This configuration relates to package-level values which do not necessarily need
 customising, as long as a user's data and output on their personal filesystem
@@ -140,8 +140,6 @@ basis.
 
 ## The `config` template {#config-template}
 
-See also [development](#config-template).
-
 To create a default configuration for the first time and save it to your
 personal system, run:
 
@@ -165,15 +163,18 @@ To update or recreate this config file, run:
 write_user_cfg(overwrite = TRUE)
 ```
 
-Though note that there is currently no conversion path for existing config files
-so any custom changes would then need to be *manually re-applied*.
+Though note that *there is currently no conversion utility for existing config
+files* so any custom changes would then need to be **manually re-applied**.
+Please make sure to back up your config file.
 
-## Default `config` values and overriding them {#default-config-values}
+## Default and custom `config` values {#config-values}
 
 ### Defaults
 
 [TODO: Describe defaults]
 
+### Custom
+
 In general, defaults can be overridden by manually editing the config.
 
 [TODO: Show examples of overriding the defaults]