streamline docs and expose example data

closes #306 closes #304 closes #303 closes #79 closes #55
subugoe · Sep 21, 2021 · 1f46bb4 · 1f46bb4
1 parent 9175a3d
commit 1f46bb4
Show file tree

Hide file tree

Showing 43 changed files with 218 additions and 248 deletions.
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -38,7 +38,7 @@ jobs:
           devtools::check(error_on = "warning")
       - name: Build Package Website
         run: |
-          muggle::build_site2()
+          muggle::build_site2(override = list(new_process = FALSE))
       - name: Build Buildtime Image
         uses: docker/build-push-action@v1
         with:

diff --git a/NAMESPACE b/NAMESPACE
@@ -11,6 +11,7 @@ export(cr_compliance_overview)
 export(cr_funder_df)
 export(cr_has_orcid)
 export(cr_tdm_df)
+export(doi_examples)
 export(draft_report)
 export(emailReport)
 export(emailReportServer)
@@ -44,7 +45,6 @@ export(runMetacheck)
 export(smtp_send_mc)
 export(tabulate_metacheckable)
 export(tdm_metrics)
-export(tu_dois)
 export(vor_issue)
 import(dplyr)
 import(purrr)

diff --git a/R/communicate.R b/R/communicate.R
@@ -99,7 +99,7 @@ mcControlsServer <- function(id, translator = mc_translator()) {
       shiny::observe(shiny.i18n::update_lang(session, lang()))
       dois <- biblids::doiEntryServer(
         id = "dois",
-        example_dois = tu_dois()[1:30],
+        example_dois = doi_examples$good[1:30],
         char_limit = 50000L,
         translator = translator,
         lang = lang

diff --git a/R/cr_md_funder.R b/R/cr_md_funder.R
@@ -32,4 +32,3 @@ empty_funder <- function(cr) {
   }
   out
 }
-
diff --git a/R/data.R b/R/data.R
@@ -1,31 +1,43 @@
-#' Some DOIs for testing
-#' @keywords internal
-#' @export
-tu_dois <- function() {
-  readr::read_lines(file = system_file2("extdata", "dois", "tu.txt"))
-}
-
-#' Long list of DOIs
-#' @noRd
-dois_many <- function() {
-  res <- readr::read_lines(file = system_file2("extdata", "dois", "many.txt"))
-  biblids::as_doi(res)
-}
+# ==== example dois
 
-#' Some troublesome DOIs for testing
-#' @noRd
-dois_weird <- function() {
-  c(
-    # these are roughly in the order of metacheckable predicates
-    "10.1000/1",
-    NA, # there's no meaningful metadata for an NA DOI
-    "doi:10.1000/1", # duplicated from above
-    "10.3389/fbioe.2020.00209", # actually from CR
-    "10.1000/2",
-    "10.1000/3", # would exceed limit of 4
-    # caused issues in https://github.com/subugoe/metacheck/issues/181
-    "10.1007/s00330-019-06284-8",
-    # caused issues in https://github.com/subugoe/metacheck/issues/181
-    "10.1007/s00431-018-3217-8"
-  )
-}
+#' DOIs included in the package for testing and illustration
+#' @format A list of [biblids::doi()] vectors, including:
+#' - `good`: Guaranteed to work (all are [is_metacheckable()]).
+#' - `many`: Long list of DOIs.
+#' - `weird`: Troublesome DOIs.
+#' - `biblids`: [biblids::doi_examples()]
+#' 
+#' @examples
+#' doi_examples$good
+#' 
+#' @family data
+#' @export
+doi_examples <- list(
+  # these are originally from TU users
+  good = biblids::as_doi(
+    readr::read_lines(
+      file = system.file("extdata", "dois", "tu.txt", package = "metacheck"))
+  ),
+  many = biblids::as_doi(
+    readr::read_lines(
+      file = system.file("extdata", "dois", "many.txt", package = "metacheck")
+    )
+  ),
+  weird = biblids::as_doi(
+    c(
+      # these are roughly in the order of metacheckable predicates
+      "10.1000/1",
+      NA, # there's no meaningful metadata for an NA DOI
+      "doi:10.1000/1", # duplicated from above
+      "10.3389/fbioe.2020.00209", # actually from CR
+      "10.1000/2",
+      "10.1000/3", # would exceed limit of 4
+      # caused issues in https://github.com/subugoe/metacheck/issues/181
+      "10.1007/s00330-019-06284-8",
+      # caused issues in https://github.com/subugoe/metacheck/issues/181
+      "10.1007/s00431-018-3217-8",
+      "10.3389/fmech.2020.566440/full"  # superfluous url fragment
+    )
+  ),
+  biblids = biblids::doi_examples()
+)
diff --git a/R/email.R b/R/email.R
@@ -119,7 +119,7 @@ block_text_centered_vec <- function(...) {
 #' @param session_id Character vector to identify current shiny session
 #' @inheritDotParams blastula::render_email
 #' @export
-mc_render_email <- function(dois = tu_dois()[1:10],
+mc_render_email <- function(dois = doi_examples$good[1:10],
                             translator = mc_translator(),
                             session_id = NULL,
                             ...) {

diff --git a/R/metacheck_package.R → R/metacheck.R b/R/metacheck_package.R → R/metacheck.R
diff --git a/R/metrics_cc.R b/R/metrics_cc.R
@@ -1,54 +1,36 @@
-#' CC license variants metrics overview
+#' Diagnose Creative Commons Licensing
+#' @family transform
+#' @examples
+#' # obtain metadata from Crossref API
+#' req <- get_cr_md(doi_examples$good)
 #'
-#' Presents normalised CC licence variants like BY (absolute and relative)
+#' # check article-level compliance
+#' out <- cr_compliance_overview(req)
+#' @name cc
+NULL
+
+#' @describeIn cc Presents normalised CC licence variants.
+#' For example, `BY` (absolute and relative).
 #'
 #' @param cc_license_check tibble, result from [license_check()]
-#'
 #' @export
-#'
 #' @examples
-#' \dontrun{
-#' my_dois <- c("10.5194/wes-2019-70", "10.1038/s41598-020-57429-5",
-#'   "10.3389/fmech.2019.00073", "10.1038/s41598-020-62245-y",
-#'   "10.1109/JLT.2019.2961931")
-#'
-#' # Workflow:
-#' # First, obtain metadata from Crossref API
-#' req <- get_cr_md(my_dois)
-#'
-#' # Then, check article-level compliance
-#' out <- cr_compliance_overview(req)
-#'
-#' # Obtain CC variants metrics
+#' # obtain CC variants metrics
 #' cc_metrics(out$cc_license_check)
-#' }
-#' @keywords internal
 cc_metrics <- function(cc_license_check = NULL) {
   is_cr_license_df(cc_license_check)
   cc_license_check %>%
     dplyr::count(indicator = .data$cc_norm, name = "value") %>%
     dplyr::mutate(prop = .data$value / sum(.data$value) * 100)
 }
 
-#' CC compliance metrics overview
-#'
-#' Presents the result of the CC compliance check (absolute and relative)
+#' @describeIn cc Presents the result of the CC compliance check.
+#' Absolute and relative normalised CC licence variants.
 #'
 #' @seealso [license_check()]
-#'
-#' @inheritParams cc_metrics
-#'
 #' @export
-#'
 #' @examples
-#' # Workflow:
-#' # First, obtain metadata from Crossref API
-#' req <- get_cr_md(tu_dois()[7:10])
-#'
-#' # Then, check article-level compliance
-#' out <- cr_compliance_overview(req)
-#'
-#' # Obtain CC compliance check resutls metrics
+#' # Obtain cc compliance check resutls metrics
 #' cc_compliance_metrics(out$cc_license_check)
 #' @keywords internal
 cc_compliance_metrics <- function(cc_license_check = NULL) {

diff --git a/R/metrics_funder.R b/R/metrics_funder.R
@@ -10,22 +10,15 @@
 #' @param funder_info tibble obtained with [cr_funder_df()] or [cr_compliance_overview()]
 #' @export
 #'
-#' @examples \dontrun{
-#' ## Some DOIs from OA articles
-#' my_dois <- c("10.5194/wes-2019-70", "10.1038/s41598-020-57429-5",
-#'   "10.3389/fmech.2019.00073", "10.1038/s41598-020-62245-y",
-#'   "10.1109/JLT.2019.2961931")
-#'
-#' # Workflow:
+#' @examples
 #' # First, obtain metadata from Crossref API
-#' req <- get_cr_md(my_dois)
+#' req <- get_cr_md(doi_examples$good)
 #'
 #' # Then, check article-level compliance
-#  out <- cr_compliance_overview(req)
+#' out <- cr_compliance_overview(req)
 #'
 #' # Obtain funder metrics overview
 #' funder_metrics(out$funder_info)
-#' }
 #' @keywords internal
 funder_metrics <- function(funder_info = NULL) {
   is_cr_funder_df(funder_info)

diff --git a/R/metrics_overview.R b/R/metrics_overview.R
@@ -18,22 +18,15 @@
 #'
 #' @export
 #'
-#' @examples \dontrun{
-#' ## Some DOIs from OA articles
-#' my_dois <- c("10.5194/wes-2019-70", "10.1038/s41598-020-57429-5",
-#'   "10.3389/fmech.2019.00073", "10.1038/s41598-020-62245-y",
-#'   "10.1109/JLT.2019.2961931")
-#'
-#' # Workflow:
+#' @examples
 #' # First, obtain metadata from Crossref API
-#' req <- get_cr_md(my_dois)
+#' req <- get_cr_md(doi_examples$good)
 #'
 #' # Then, check article-level compliance
-#  out <- cr_compliance_overview(my_dois)
+#' out <- cr_compliance_overview(req)
 #'
 #' # Finally, obtain compliance metrics overview
-#' metrics_overview(out)
-#' }
+#' metrics_overview(out$cr_overview)
 #' @keywords internal
 metrics_overview <- function(cr_overview = NULL) {
   is_cr_overview_df(cr_overview)

diff --git a/R/metrics_tdm.R b/R/metrics_tdm.R
@@ -12,22 +12,15 @@
 #' @param tdm tibble obtained with [cr_tdm_df()] or [cr_compliance_overview()]
 #' @export
 #'
-#' @examples \dontrun{
-#' ## Some DOIs from OA articles
-#' my_dois <- c("10.5194/wes-2019-70", "10.1038/s41598-020-57429-5",
-#'   "10.3389/fmech.2019.00073", "10.1038/s41598-020-62245-y",
-#'   "10.1109/JLT.2019.2961931")
-#'
-#' # Workflow:
+#' @examples
 #' # First, obtain metadata from Crossref API
-#' req <- get_cr_md(my_dois)
+#' req <- get_cr_md(doi_examples$good)
 #'
 #' # Then, check article-level compliance
-#  out <- cr_compliance_overview(req)
+#' out <- cr_compliance_overview(req)
 #'
 #' # Finally, obtain TDM metrics overview
 #' tdm_metrics(out$tdm)
-#' }
 #' @keywords internal
 tdm_metrics <- function(tdm = NULL) {
   is_cr_tdm_df(tdm)

diff --git a/R/report.R b/R/report.R
@@ -41,7 +41,9 @@ draft_report <- function(lang = mc_langs, ...) {
 #' @inheritDotParams rmarkdown::render
 #' @inheritParams mcControlsServer
 #' @export
-render_report <- function(dois = tu_dois(), translator = mc_translator(), ...) {
+render_report <- function(dois = doi_examples$good,
+                          translator = mc_translator(),
+                          ...) {
   stopifnot(!shiny::is.reactive(dois))
   checkmate::assert_vector(dois, min.len = 1, null.ok = FALSE)
   dois <- biblids::as_doi(dois)
@@ -58,7 +60,7 @@ render_report <- function(dois = tu_dois(), translator = mc_translator(), ...) {
 #' @noRd
 knit_child_report <- function(...) {
   # knit_child does not know params, so these have to be in env
-  params <<- list(dois = tu_dois())
+  params <<- list(dois = doi_examples$good)
   res <- knitr::knit_child(
     path_report_rmd(...),
     quiet = TRUE

diff --git a/inst/extdata/dois/many.txt b/inst/extdata/dois/many.txt
@@ -1583,4 +1583,6 @@
 10.2478/s11756-020-00474-2
 10.2478/s11756-020-00475-1
 10.3758/s13415-018-00647-2
-10.4153/cjm-2017-045-0
+10.4153/cjm-2017-045-0
+10.5194/wes-5-1375-2020
+10.5194/wes-5-721-2020
diff --git a/inst/extdata/dois/tu.txt b/inst/extdata/dois/tu.txt
@@ -1,4 +1,3 @@
-10.5194/wes-2019-70
 10.1038/s41598-020-57429-5
 10.3389/fmech.2019.00073
 10.1038/s41598-020-62245-y
@@ -51,9 +50,7 @@
 10.3389/fmech.2020.00039
 10.3389/fmicb.2020.01284
 10.1016/j.envint.2020.105867
-10.5194/wes-5-819-202
 10.1016/j.egyr.2020.06.028
-10.5194/wes-5-721-2020
 10.1186/s12939-020-01191-7
 10.3390/en13081993
 10.3390/su12083394
@@ -81,7 +78,6 @@
 10.3389/fmech.2020.00057
 10.1088/1748-9326/aba2fe
 10.5194/hess-24-3835-2020
-10.1039/D0RA05997H
 10.3389/fbioe.2020.00854
 10.3389/fnins.2020.00795
 10.3389/fmech.2020.00069
@@ -120,12 +116,10 @@
 10.3390/recycling5030019
 10.3390/mi11090866
 10.3390/en13205348
-10.3389/fmech.2020.566440/full
 10.1088/1748-9326/abbd63
 10.3390/su12197984
 10.5194/gmd-13-4435-2020
 10.36900/suburban.v8i3.523
-10.5194/wes-5-1375-2020
 10.1002/ejlt.202000213
 10.1002/cbic.202000257
 10.1002/adfm.202007294

diff --git a/inst/rmarkdown/templates/bericht/skeleton/skeleton.Rmd b/inst/rmarkdown/templates/bericht/skeleton/skeleton.Rmd
@@ -2,7 +2,7 @@
 output: blastula::blastula_email
 title: "Metacheck Bericht"
 params:
-  dois: !r metacheck:::tu_dois()
+  dois: !r metacheck::doi_examples$good
   translator: !r metacheck::mc_translator()
   session_id: NULL
 ---

diff --git a/inst/rmarkdown/templates/report/skeleton/skeleton.Rmd b/inst/rmarkdown/templates/report/skeleton/skeleton.Rmd
@@ -2,7 +2,7 @@
 output: blastula::blastula_email
 title: "Metacheck Report"
 params:
-  dois: !r metacheck:::tu_dois()
+  dois: !r metacheck::doi_examples$good
   translator: !r metacheck::mc_translator()
   session_id: NULL
 ---
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,4 +32,3 @@ empty_funder <- function(cr) {
		}
		out
		}