Merge pull request #22 from fbenke-pik/master

Add support for extrapage attribute
pik-piam · Nov 23, 2023 · 9dd09b2 · 9dd09b2
2 parents 23b6fd6 + 78ed638
commit 9dd09b2
Show file tree

Hide file tree

Showing 23 changed files with 623 additions and 264 deletions.
diff --git a/.buildlibrary b/.buildlibrary
@@ -1,4 +1,4 @@
-ValidationKey: '2603874'
+ValidationKey: '2755760'
 AutocreateReadme: yes
 AcceptedWarnings:
 - 'Warning: package ''.*'' was built under R version'

diff --git a/.github/workflows/check.yaml b/.github/workflows/check.yaml
@@ -1,5 +1,3 @@
-# Run CI for R using https://eddelbuettel.github.io/r-ci/
-
 name: check
 
 on:
@@ -8,92 +6,45 @@ on:
   pull_request:
     branches: [main, master]
 
-env:
-  USE_BSPM: "true"
-  _R_CHECK_FORCE_SUGGESTS_: "false"
-  NO_BINARY_INSTALL_R_PACKAGES: 'c("madrat", "magclass", "citation", "gms", "goxygen", "GDPuc", "roxygen2")'
-
 jobs:
   check:
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
 
-      - name: Bootstrap
-        run: |
-          sudo chown runner -R .
-          sudo locale-gen en_US.UTF-8
-          sudo add-apt-repository -y ppa:ubuntugis/ppa
-          curl -OLs https://eddelbuettel.github.io/r-ci/run.sh
-          chmod 0755 run.sh
-          ./run.sh bootstrap
-          rm -f bspm_*.tar.gz
-
-      - name: Enable r-universe repo, modify bspm integration
-        run: |
-          # install packages from https://pik-piam.r-universe.dev and CRAN
-          echo '
-          options(repos = c(universe = "https://pik-piam.r-universe.dev",
-                            CRAN = "https://cloud.r-project.org"))
-          ' >> .Rprofile
-          cat .Rprofile
-          # modify bspm integration to never install binary builds of PIK CRAN packages
-          sudo sed -i '/bspm::enable()/d' /etc/R/Rprofile.site
-          # need double % because of printf, %s is replaced with "$NO_BINARY_INSTALL_R_PACKAGES" (see "env:" above)
-          printf '
-          local({
-            expr <- quote({
-              if (!is.null(repos)) {
-                noBinaryInstallRPackages <- %s
-                pkgs <- c(bspm::install_sys(pkgs[!pkgs %%in%% noBinaryInstallRPackages]),
-                          pkgs[pkgs %%in%% noBinaryInstallRPackages])
-              }
-              type <- "source"
-            })
-            trace(utils::install.packages, expr, print = FALSE)
-          })
-          ' "$NO_BINARY_INSTALL_R_PACKAGES" | sudo tee --append /etc/R/Rprofile.site >/dev/null
-          cat /etc/R/Rprofile.site
-
-      - name: Set up Pandoc
-        uses: r-lib/actions/setup-pandoc@v2
+      - uses: r-lib/actions/setup-pandoc@v2
 
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v4
+      - uses: r-lib/actions/setup-r@v2
         with:
-          python-version: 3.9
+          use-public-rspm: true
+          extra-repositories: "https://rse.pik-potsdam.de/r/packages"
 
-      - name: Cache R libraries
-        if: ${{ !env.ACT }} # skip when running locally via nektos/act
-        uses: pat-s/always-upload-cache@v3
+      - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          path: /usr/local/lib/R/
-          key: 3-${{ runner.os }}-usr-local-lib-R-${{ hashFiles('DESCRIPTION') }}
-          restore-keys: |
-            3-${{ runner.os }}-usr-local-lib-R-
-
-      - name: Restore R library permissions
-        run: |
-          sudo chmod 2777 /usr/local/lib/R /usr/local/lib/R/site-library
-
-      - name: Install dependencies
-        run: |
-          ./run.sh install_aptget libhdf5-dev libharfbuzz-dev libfribidi-dev
-          ./run.sh install_all
-          ./run.sh install_r_binary covr rstudioapi
-          ./run.sh install_r lucode2
+          extra-packages: |
+            gamstransfer=?ignore
+            any::lucode2
+            any::covr
+            any::madrat
+            any::magclass
+            any::citation
+            any::gms
+            any::goxygen
+            any::GDPuc
+          # piam packages also available on CRAN (madrat, magclass, citation,
+          # gms, goxygen, GDPuc) will usually have an outdated binary version
+          # available; by using extra-packages we get the newest version
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
 
       - name: Install python dependencies if applicable
         run: |
           [ -f requirements.txt ] && python -m pip install --upgrade pip wheel || true
           [ -f requirements.txt ] && pip install -r requirements.txt || true
 
-      - name: Remove bspm integration # to get rid of error when running install.packages
-        run: |
-          sudo sed -i '/  trace(utils::install.packages, expr, print = FALSE)/d' /etc/R/Rprofile.site
-          cat /etc/R/Rprofile.site
-
       - name: Verify validation key
         shell: Rscript {0}
         run: lucode2:::validkey(stopIfInvalid = TRUE)
@@ -106,6 +57,8 @@ jobs:
 
       - name: Test coverage
         shell: Rscript {0}
-        run: covr::codecov(quiet = FALSE)
+        run: |
+          nonDummyTests <- setdiff(list.files("./tests/testthat/"), c("test-dummy.R", "_snaps"))
+          if(length(nonDummyTests) > 0) covr::codecov(quiet = FALSE)
         env:
           NOT_CRAN: "true"
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -3,7 +3,7 @@
 exclude: '^tests/testthat/_snaps/.*$'
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     -   id: check-case-conflict
     -   id: check-json
@@ -15,7 +15,7 @@ repos:
     -   id: mixed-line-ending
 
 -   repo: https://github.com/lorenzwalthert/precommit
-    rev: v0.3.2.9013
+    rev: v0.3.2.9025
     hooks:
     -   id: parsable-R
     -   id: deps-in-desc

diff --git a/CITATION.cff b/CITATION.cff
@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using the metadata from this file.
 type: software
 title: 'goxygen: In-Code Documentation for ''GAMS'''
-version: 1.3.3
-date-released: '2023-08-09'
+version: 1.4.0
+date-released: '2023-11-23'
 abstract: A collection of tools which extract a model documentation from 'GAMS' code
   and comments. In order to use the package you need to install 'pandoc' and 'pandoc-citeproc'
   first (<https://pandoc.org/>).
@@ -20,6 +20,9 @@ authors:
 - family-names: Baumstark
   given-names: Lavinia
   email: [email protected]
+- family-names: Benke
+  given-names: Falk
+  email: [email protected]
 license: BSD-2-Clause
 repository-code: https://github.com/pik-piam/goxygen
 doi: 10.5281/zenodo.1411404

diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,19 +1,20 @@
 Package: goxygen
 Type: Package
 Title: In-Code Documentation for 'GAMS'
-Version: 1.3.3
-Date: 2023-08-09
+Version: 1.4.0
+Date: 2023-11-23
 Authors@R: c(person("Jan Philipp", "Dietrich", email = "[email protected]", role = c("aut","cre")),
              person("Kristine", "Karstens", email = "[email protected]", role = "aut"),
              person("David", "Klein", email = "[email protected]", role = "aut"),
-             person("Lavinia", "Baumstark", email = "[email protected]", role = "aut"))
+             person("Lavinia", "Baumstark", email = "[email protected]", role = "aut"),
+             person("Falk", "Benke", email = "[email protected]", role = "aut"))
 Description: A collection of tools which extract a model documentation from 'GAMS' code and comments. 
              In order to use the package you need to install 'pandoc' and 'pandoc-citeproc' 
              first (<https://pandoc.org/>).
 Imports:
     pander,
     stringi,
-    gms,
+    gms (>= 0.26.3),
     citation,
     withr,
     yaml

diff --git a/R/appendExtraPageBlocks.R b/R/appendExtraPageBlocks.R
@@ -0,0 +1,23 @@
+#' appendExtraPageBlocks
+#'
+#' A helper to merge two nested lists describing extra page blocks.
+#' The lists have the page name on the first level and flattened documentation
+#' blocks on the second level. It is ensured that elements for the
+#' same page are grouped in the same list.
+#'
+#' @param blocks a nested list for extra page blocks per page
+#' @param add a seccond nested list for extra page blocks per page to be
+#' appended to the first one
+#'
+#' @author Falk Benke
+appendExtraPageBlocks <- function(blocks, add) {
+  for (k in seq_along(add)) {
+    page <- names(add[k])
+    if (page %in% names(blocks)) {
+      blocks[[page]] <- append(blocks[[page]], add[[k]])
+    } else {
+      blocks[[page]] <- add[[k]]
+    }
+  }
+  return(blocks)
+}
diff --git a/R/createListModularCode.R b/R/createListModularCode.R
@@ -156,8 +156,10 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
       outSub <- list()
       outSub$realizations <- list()
       files <- list.files(path = "core", pattern = "\\.gms")
-      paths <- paste0("core/", files)
+      paths <- file.path("core", files)
+
       outSub$realizations[["core"]] <- extractDocumentation(paths, start_type = "equations")
+
     } else {
       rea <- strsplit(cc$modulesInfo[m, "realizations"], ",")[[1]]
       folder <- cc$modulesInfo[m, "folder"]
@@ -177,6 +179,7 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
         # but ordering it based on the order of mention in realization.gms. Not
         # mentioned files will be added at the end.
         paths <- union(intersect(mentionedPaths, existingPaths), existingPaths)
+
         outSub$realizations[[r]] <- extractDocumentation(paths, start_type = "equations")
       }
     }
@@ -195,8 +198,14 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
 
   # write doc files
   full <- list()
+
   data <- extractDocumentation(mainfile)
+  data <- flattenPageBlockList(data)
+  extraPageBlocks <- data$extraPageBlocks
+  data <- data$blocks
+
   data$citation <- citation
+
   full[["index"]] <- createIndexPage(data)
 
   # take only all modules into account or also core
@@ -205,11 +214,24 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
   } else {
     mLoop <- setdiff(sort(names(out)), "core")
   }
+
   for (m in mLoop) {
-    data <- append(out[[m]], collectRealizations(m, cc))
+    realizations <- collectRealizations(m, cc)
+    extract <- flattenPageBlockList(realizations)
+
+    realizations <- extract$blocks
+    extraPageBlocks <- appendExtraPageBlocks(extraPageBlocks, extract$extraPageBlocks)
+    data <- append(out[[m]], realizations)
     data$name <- m
     data$seealso <- collectSeealso(interfaces[[m]], m, cc$modulesInfo)
     full[[m]] <- createModulePage(data, docfolder = docfolder)
   }
+
+  for (i in names(extraPageBlocks)) {
+    data <- mergeDocumentation(extraPageBlocks[[i]])
+    data$name <- i
+    full[[i]] <- createModulePage(data, docfolder = docfolder)
+  }
+
   return(full)
 }
diff --git a/R/createListSimpleCode.R b/R/createListSimpleCode.R
@@ -15,19 +15,36 @@ createListSimpleCode <- function(path = ".", citation = NULL, mainfile = "main.g
 
   # write doc files
   full <- list()
+
   data <- extractDocumentation(mainfile)
+  data <- flattenPageBlockList(data)
+  extraPageBlocks <- data$extraPageBlocks
+  data <- data$blocks
+
   data$citation <- citation
   full[["index"]] <- createIndexPage(data)
 
   files <- setdiff(list.files(pattern = "\\.gms$", recursive = TRUE), mainfile)
   for (f in files) {
     fname <- sub("\\.gms$", "", gsub("/", "_", f, fixed = TRUE))
     data <- extractDocumentation(f)
+    extract <- flattenPageBlockList(data)
+    data <- extract$blocks
+
+    extraPageBlocks <- appendExtraPageBlocks(extraPageBlocks, extract$extraPageBlocks)
+
     if (length(data) > 0) {
       if (is.null(data$title)) data$title <- fname
       data$name <- f
       full[[fname]] <- createSimplePage(data)
     }
   }
+
+  for (i in names(extraPageBlocks)) {
+    data <- mergeDocumentation(extraPageBlocks[[i]])
+    data$name <- i
+    full[[i]] <- createSimplePage(data)
+  }
+
   return(full)
 }