Merge branch 'main' into clean-separation

.Rbuildignore

@@ -4,3 +4,6 @@
 ^\.Rproj\.user$
 ^LICENSE\.md$
 ^\.vscode$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

.github/workflows/pkgdown.yaml

@@ -0,0 +1,61 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown
+
+permissions:
+  contents: read
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+  # Deploy the artifacts, separate jobs to minimize the grantet wride permissions.
+  deploy:
+    needs: pkgdown
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      # url: ${{ steps.deployment.outputs.page_url }}
+      url: https://disyinformationssysteme.github.io/cadenza-analytics-r/
+    steps:
+      - id: deployment
+        name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,3 +4,4 @@
 .httr-oauth
 .DS_Store
 .vscode
+docs

DESCRIPTION

@@ -5,7 +5,7 @@ Authors@R: c(
     person("Matthias", "Theobald", email = "[email protected]", role = c("aut", "cre")),
     person("Lossow", "Stefan", email = "[email protected]", role = c("aut")),
     person("Herrmann", "Marius", email = "[email protected]", role = c("aut")),
-    person("Babenhauserheide", "Arne", email = "[email protected]", role = c("aut")),
+    person("Babenhauserheide", "Arne", email = "[email protected]", role = c("aut"), comment = c(ORCID = "0000-0003-1381-8277")),
     person("Disy", role = c("cph"))
   )
 Description: Cadenza Analytics Extensions enable complex data analytics to be integrated via external services. This package provides the tooling to create such Analytics Extensions easily from R.
@@ -29,3 +29,4 @@ Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
 Suggests:
     sf
+URL: https://disyinformationssysteme.github.io/cadenza-analytics-r/, https://github.com/DisyInformationssysteme/cadenza-analytics-r

R/custom-parsers.R

@@ -25,16 +25,16 @@ detect_boundary <- function(content_type) {
 
 
 
-#' Custom parsers
+#' Cadenza parsers
 #'
 #' A parser is responsible for returning a valid R object based on the
 #' document-type.  The Cadenza parser takes a multipart form with a
 #' specific structure and returns a dataframe.
 #'
-#' See [plumber::parser_form()] for details and
-#' [plumber::registered_parsers()] for a list of registered parsers names.
+#' See [plumber::registered_parsers()] for a list of registered parsers names.
+#'
+#' @describeIn parsers Parse multipart-form request from Cadenza. Also see [plumber::parser_form()].
 #'
-#' @describeIn parsers Parse multipart-form request from Cadenza
 #' @return
 #'  A list with the following elements:
 #'  - data: the data sent by Cadenza; Can be a dataframe or a list
@@ -85,8 +85,9 @@ parser_cadenza <- function() {
   }
 }
 
-#' @describeIn parsers Parse any delimited files. See [vroom::vroom()]
-#'     for details.
+#' @describeIn parsers Parse any delimiter separated value data.
+#'     Also see [vroom::vroom()].
+#'
 #' @param ... Additional arguments passed on to [vroom::vroom()].
 #' @export
 parser_delim <- function(...) {

R/custom-serializer-capabilities.R

@@ -20,7 +20,7 @@
 #' @return a GetCapabilities response.
 #' @export
 #'
-#' @examples
+#' @examplesIf interactive()
 #' function() {
 #'   extension(
 #'     printName = "Data Generation",
@@ -52,18 +52,24 @@ serializer_cadenza_capabilities <- function(...) { # nolint symbol length
 }
 
 #' The extension description
+#'
+#' See the examples in [serializer_cadenza_capabilities()].
 #' @export
 extension <- function(...) {
   list(...)
 }
 
-#' A group of attributes used in the extension
+#' A group of attributes used in the extension.
+#'
+#' See the examples in [serializer_cadenza_capabilities()].
 #' @export
 attribute_group <- function(...) {
   list(...)
 }
 
-#' A parameter that can or must be passed to the extension
+#' A parameter that can or must be passed to the extension.
+#'
+#' See the examples in [serializer_cadenza_capabilities()].
 #' @export
 parameter <- function(...) {
   list(...)

R/custom-serializer-discovery.R

@@ -14,19 +14,20 @@
 
 #' Build the Discovery GET-response.
 #'
-#' @param discovery A list with an extension of a extension_references.
-#' Each requires a printName, extensionType, and attributeGroups.
-#' It can optionally take parameters.
+#' @param ... a [discovery()] structure.
+#'
 #' @return a discovery response.
 #' @export
 #'
-#' @examples
+#' @examplesIf interactive()
 #' function() {
-#'   list(
-#'     extension_reference(
-#'       extensionPrintName = "The Name",
-#'       extensionType = "calculation",
-#'       relativePath = "/path-of-extension"
+#'   discovery(
+#'     extensions = list(
+#'       extension_reference(
+#'         extensionPrintName = "The Name",
+#'         extensionType = "calculation",
+#'         relativePath = "/path-of-extension"
+#'       )
 #'     )
 #'   )
 #' }
@@ -36,14 +37,22 @@ serializer_cadenza_discovery <- function(...) { # nolint symbol length
   serializer_unboxed_json(...)
 }
 
-#' The extension description
+#' The description of one extension
+#'
+#' @param ... requires a printName, extensionType, and attributeGroups.
+#' It can optionally take additional parameters.
+#' For examples, see [serializer_cadenza_discovery()]
+#'
 #' @export
 extension_reference <- function(...) {
   list(...)
 }
 
 
-#' The extension description
+#' The description for available extensions
+#'
+#' @param extensions a list of [extension_reference()]'s. For examples, see [serializer_cadenza_discovery()]
+#'
 #' @export
 discovery <- function(...) {
   list(...)

R/custom-serializer-enrichment-calculation.R

@@ -208,7 +208,7 @@ glue_multipart <- function(body, type, boundary) {
 #'     strings and has to have the attribute `type` with the HTML
 #'     content type of each part.
 #' @param boundary The boundary string with which the parts are to be
-#'     separated.  If `NULL` a random string of 30 characters will be
+#'     separated.  If `NULL`, a random string of 30 characters will be
 #'     generated and used.
 #' @param ... Additional arguments to be passed to the serialize
 #'     function.
@@ -217,13 +217,15 @@ glue_multipart <- function(body, type, boundary) {
 #' @export
 #'
 #' @examples
+#' \dontrun{
 #' pr() |>
 #'   pr_get(
 #'     "/form",
 #'     handler = function() list(data.frame(x = rnorm(10), y = runif(10)),
 #'                               list(param = "b", value = 12)),
 #'     serializer = serializer_multi(
 #'       serialiize_fn = function(val) lapply(val, )))
+#' }
 serializer_multi <- function(serialize_fn, boundary = NULL, ...) {
   if (is.null(boundary)) {
     boundary <- stringi::stri_rand_strings(n = 1L, length = 30L)

R/custom-serializer-visualization.R

@@ -20,11 +20,18 @@ boundary <- stringi::stri_rand_strings(n = 1L, length = 30L)
 #' @param res The Plumber response construct
 #' @param plotfile The plot file created in the Plumber R file
 #'
-#' @return res The Plumber response construct adjusted
+#' @return The Plumber response construct with the plot data added
 #' @export
 #'
 #' @examples
-#' res <- as_cadenza_visualization(res, plotfile)
+#' png(file = "plot.png")
+#' plot(list(1), list(1))
+#' dev.off()
+#' res <- list("injected from plumber")
+#' res <- as_cadenza_visualization(res, "plot.png")
+#' res$status
+#' res$headers
+#' length(res$body)
 
 as_cadenza_visualization <- function(res, plotfile) {