From 619e26b89ef66ce9bb85676f36e1f828ab44fafa Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Wed, 6 Nov 2024 16:17:56 -0500 Subject: [PATCH 01/10] add functions to build html reference manuals --- DESCRIPTION | 2 +- R/build_html_mans.R | 187 ++++++++++++++++++++++++++++++++++++++++++++ man/html-manuals.Rd | 100 +++++++++++++++++++++++ 3 files changed, 288 insertions(+), 1 deletion(-) create mode 100644 R/build_html_mans.R create mode 100644 man/html-manuals.Rd diff --git a/DESCRIPTION b/DESCRIPTION index bae8b05..272a571 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -24,5 +24,5 @@ Collate: AllClasses.R AllGenerics.R as-methods.R htmlDoc-methods.R htmlFilename-methods.R htmlValue-methods.R show-methods.R getPackNames.R packageDetails.R pump.R repository.R showvoc.R getPackageNEWS.R validation_tests.R recommendBiocViews.R - dump_concept.R + dump_concept.R build_html_mans.R VignetteBuilder: knitr diff --git a/R/build_html_mans.R b/R/build_html_mans.R new file mode 100644 index 0000000..b9acdd3 --- /dev/null +++ b/R/build_html_mans.R @@ -0,0 +1,187 @@ + +#' @name html-manuals +#' +#' @title Helper functions to generate HTML pages for reference manuals +#' +#' @param package_dir `character(1)` The local path to a package for which to +#' build the aliases and cross-ref databases (`rds` files). +#' +#' @param src_base `character(1)` The path to the base hosting directory for the +#' package repository. This is typically a location on the BBS server. +#' +#' @examples +#' if (interactive()) { +#' library(BiocPkgTools) +#' bioc_sub <- pkgBiocDeps( +#' "SummarizedExperiment", pkgType = "software", +#' recursive = TRUE, only.bioc = TRUE +#' ) +#' bioc_sub <- unlist(bioc_sub, use.names = FALSE) +#' +#' ## generate from Bioc package source dirs +#' packages <- file.path(normalizePath("~/bioc"), bioc_sub) +#' src_base <- "~/minibioc/packages/3.20/bioc" +#' +#' for (package in packages) { +#' build_db_from_source(package, src_base) +#' } +#' } +#' @export +build_db_from_source <- function(package_dir, src_base) { + tmp_dir <- tempdir() + package <- basename(package_dir) + package_web_dir <- file.path(src_base, "web", "packages", package) + if (!dir.exists(package_web_dir)) + dir.create(package_web_dir, recursive = TRUE) + db <- tools::Rd_db(dir = package_dir) + + ## aliases.rds + aliases <- lapply(db, tools:::.Rd_get_metadata, "alias") + afile <- file.path(tmp_dir, "aliases.rds") + saveRDS(aliases, file = afile, version = 2) + atofile <- file.path(package_web_dir, "aliases.rds") + file.copy( + from = afile, + to = atofile + ) + message(atofile) + + ## rdxrefs.rds + rdxrefs <- lapply(db, tools:::.Rd_get_xrefs) + rdxrefs <- cbind(do.call(rbind, rdxrefs), + Source = rep.int(names(rdxrefs), sapply(rdxrefs, NROW))) + xfile <- file.path(tmp_dir, "rdxrefs.rds") + saveRDS(rdxrefs, file = xfile, version = 2) + xtofile <- file.path(package_web_dir, "rdxrefs.rds") + file.copy( + from = xfile, + to = xtofile + ) + message(xtofile) +} + +#' @rdname html-manuals +#' +#' @param web_dir `character(1)` The `web/packages` local directory that is +#' also hosted on the website e.g., for CRAN +#' \url{https://cran.r-project.org/web/packages/} +#' +#' @param aliases_db_file `character(1)` The file path to `aliases.rds` file +#' generated by the `build_db_from_source` function. +#' +#' @param force `logical(1)` If `FALSE`, the function will only update the +#' database entries for which the aliases/rdxrefs file is more recent than the +#' database file. If `TRUE`, the function will read all aliases/rdxrefs files. +#' +#' @examples +#' if (interactive()) { +#' src_base <- "~/minibioc/packages/3.20/bioc/" +#' web_dir <- file.path(src_base, "web", "packages") +#' +#' meta_folder <- file.path(contrib.url(src_base), "Meta") +#' if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) +#' aliases_db_file <- file.path(meta_folder, "aliases.rds") +#' +#' meta_aliases_db <- build_meta_aliases_db(web_dir, aliases_db_file) +#' +#' saveRDS(meta_aliases_db, aliases_db_file, version = 2) +#' } +#' @export +build_meta_aliases_db <- + function(web_dir, aliases_db_file, force = FALSE) +{ + files <- Sys.glob(file.path(web_dir, "*", "aliases.rds")) + packages <- basename(dirname(files)) + if (force || !is_file(aliases_db_file)) { + db <- lapply(files, readRDS) + names(db) <- packages + } else { + db <- readRDS(aliases_db_file) + ## Drop entries in db not in package web area. + db <- db[!is.na(match(names(db), packages))] + ## Update entries for which aliases file is more recent than the + ## db file. + mtimes <- file.mtime(files) + files <- files[mtimes >= file.mtime(aliases_db_file)] + db[basename(dirname(files))] <- lapply(files, readRDS) + } + + db[sort(names(db))] +} + +is_file <- function(x) file.exists(x) && !file.info(x)[["isdir"]] + +#' @rdname html-manuals +#' +#' @param rdxrefs_db_file `character(1)` The file path to `rdxrefs.rds` file +#' generated by the `build_db_from_source` function. +#' +#' @examples +#' if (interactive()) { +#' src_base <- "~/minibioc/packages/3.20/bioc/" +#' web_dir <- file.path(src_base, "web", "packages") +#' +#' meta_folder <- file.path(contrib.url(src_base), "Meta") +#' if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) +#' rdxrefs_db_file <- file.path(meta_folder, "rdxrefs.rds") +#' +#' meta_rdxrefs_db <- build_meta_rdxrefs_db(web_dir, rdxrefs_db_file) +#' +#' saveRDS(meta_rdxrefs_db, rdxrefs_db_file, version = 2) +#' } +#' @export +build_meta_rdxrefs_db <- + function(web_dir, rdxrefs_db_file, force = FALSE) +{ + files <- Sys.glob(file.path(web_dir, "*", "rdxrefs.rds")) + packages <- basename(dirname(files)) + if(force || !is_file(rdxrefs_db_file)) { + db <- lapply(files, readRDS) + names(db) <- packages + } else { + db <- readRDS(rdxrefs_db_file) + ## Drop entries in db not in package web area. + db <- db[!is.na(match(names(db), packages))] + ## Update entries for which rdxrefs file is more recent than the + ## db file. + mtimes <- file.mtime(files) + files <- files[mtimes >= file.mtime(rdxrefs_db_file)] + db[basename(dirname(files))] <- lapply(files, readRDS) + } + + db[sort(names(db))] +} + +#' @rdname html-manuals +#' +#' @param package_dirs `character()` A vector of local package directories. +#' +#' @examples +#' if (interative()) { +#' library(BiocPkgTools) +#' bioc_sub <- pkgBiocDeps( +#' "SummarizedExperiment", pkgType = "software", +#' recursive = TRUE, only.bioc = TRUE +#' ) +#' bioc_sub <- unlist(bioc_sub, use.names = FALSE) +#' +#' ## generate from Bioc package source dirs +#' packages <- file.path(normalizePath("~/bioc"), bioc_sub) +#' src_base <- "~/minibioc/packages/3.20/bioc" +#' +#' build_html_mans(packages, src_base) +#' } +#' @export +build_html_mans <- function(package_dirs, src_base) { + packages <- basename(package_dirs) + html_dir <- file.path(src_base, "manuals") + if (!dir.exists(html_dir)) dir.create(html_dir, recursive = TRUE) + outfiles <- file.path(html_dir, paste0(packages, ".html")) + for (i in seq_along(package_dirs)) { + tools::pkg2HTML( + dir = package_dirs[i], + out = outfiles[i] + ) + } + outfiles +} diff --git a/man/html-manuals.Rd b/man/html-manuals.Rd new file mode 100644 index 0000000..15ab7eb --- /dev/null +++ b/man/html-manuals.Rd @@ -0,0 +1,100 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/build_html_mans.R +\name{html-manuals} +\alias{html-manuals} +\alias{build_db_from_source} +\alias{build_meta_aliases_db} +\alias{build_meta_rdxrefs_db} +\alias{build_html_mans} +\title{Helper functions to generate HTML pages for reference manuals} +\usage{ +build_db_from_source(package_dir, src_base) + +build_meta_aliases_db(web_dir, aliases_db_file, force = FALSE) + +build_meta_rdxrefs_db(web_dir, rdxrefs_db_file, force = FALSE) + +build_html_mans(package_dirs, src_base) +} +\arguments{ +\item{package_dir}{`character(1)` The local path to a package for which to +build the aliases and cross-ref databases (`rds` files).} + +\item{src_base}{`character(1)` The path to the base hosting directory for the +package repository. This is typically a location on the BBS server.} + +\item{web_dir}{`character(1)` The `web/packages` local directory that is +also hosted on the website e.g., for CRAN +\url{https://cran.r-project.org/web/packages/}} + +\item{aliases_db_file}{`character(1)` The file path to `aliases.rds` file +generated by the `build_db_from_source` function.} + +\item{force}{`logical(1)` If `FALSE`, the function will only update the +database entries for which the aliases/rdxrefs file is more recent than the +database file. If `TRUE`, the function will read all aliases/rdxrefs files.} + +\item{rdxrefs_db_file}{`character(1)` The file path to `rdxrefs.rds` file +generated by the `build_db_from_source` function.} + +\item{package_dirs}{`character()` A vector of local package directories.} +} +\description{ +Helper functions to generate HTML pages for reference manuals +} +\examples{ +if (interactive()) { + library(BiocPkgTools) + bioc_sub <- pkgBiocDeps( + "SummarizedExperiment", pkgType = "software", + recursive = TRUE, only.bioc = TRUE + ) + bioc_sub <- unlist(bioc_sub, use.names = FALSE) + + ## generate from Bioc package source dirs + packages <- file.path(normalizePath("~/bioc"), bioc_sub) + src_base <- "~/minibioc/packages/3.20/bioc" + + for (package in packages) { + build_db_from_source(package, src_base) + } +} +if (interactive()) { + src_base <- "~/minibioc/packages/3.20/bioc/" + web_dir <- file.path(src_base, "web", "packages") + + meta_folder <- file.path(contrib.url(src_base), "Meta") + if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) + aliases_db_file <- file.path(meta_folder, "aliases.rds") + + meta_aliases_db <- build_meta_aliases_db(web_dir, aliases_db_file) + + saveRDS(meta_aliases_db, aliases_db_file, version = 2) +} +if (interactive()) { + src_base <- "~/minibioc/packages/3.20/bioc/" + web_dir <- file.path(src_base, "web", "packages") + + meta_folder <- file.path(contrib.url(src_base), "Meta") + if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) + rdxrefs_db_file <- file.path(meta_folder, "rdxrefs.rds") + + meta_rdxrefs_db <- build_meta_rdxrefs_db(web_dir, rdxrefs_db_file) + + saveRDS(meta_rdxrefs_db, rdxrefs_db_file, version = 2) +} +if (interative()) { + library(BiocPkgTools) + bioc_sub <- pkgBiocDeps( + "SummarizedExperiment", pkgType = "software", + recursive = TRUE, only.bioc = TRUE + ) + bioc_sub <- unlist(bioc_sub, use.names = FALSE) + + ## generate from Bioc package source dirs + packages <- file.path(normalizePath("~/bioc"), bioc_sub) + src_base <- "~/minibioc/packages/3.20/bioc" + + build_html_mans(packages, src_base) +} +} From 0e9a27fbe20603af7502998696e2aa4d38b5ddcb Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Mon, 18 Nov 2024 11:55:53 -1000 Subject: [PATCH 02/10] move html files to manuals/pkg/man/pkg.html --- R/build_html_mans.R | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/R/build_html_mans.R b/R/build_html_mans.R index b9acdd3..ae850e9 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -174,9 +174,9 @@ build_meta_rdxrefs_db <- #' @export build_html_mans <- function(package_dirs, src_base) { packages <- basename(package_dirs) - html_dir <- file.path(src_base, "manuals") - if (!dir.exists(html_dir)) dir.create(html_dir, recursive = TRUE) - outfiles <- file.path(html_dir, paste0(packages, ".html")) + man_dir <- file.path(src_base, "manuals") + if (!dir.exists(man_dir)) dir.create(man_dir, recursive = TRUE) + outfiles <- file.path(man_dir, packages, "man", paste0(packages, ".html")) for (i in seq_along(package_dirs)) { tools::pkg2HTML( dir = package_dirs[i], From 5f387e51226f961230a43a27d4c4c82761835484 Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Mon, 18 Nov 2024 12:17:52 -1000 Subject: [PATCH 03/10] rename src_base to src_destDir --- DESCRIPTION | 2 ++ NAMESPACE | 4 ++++ R/build_html_mans.R | 32 ++++++++++++++++---------------- man/html-manuals.Rd | 28 ++++++++++++++-------------- 4 files changed, 36 insertions(+), 30 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 272a571..37d2f79 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -26,3 +26,5 @@ Collate: AllClasses.R AllGenerics.R as-methods.R htmlDoc-methods.R getPackageNEWS.R validation_tests.R recommendBiocViews.R dump_concept.R build_html_mans.R VignetteBuilder: knitr +RoxygenNote: 7.3.2 +Encoding: UTF-8 diff --git a/NAMESPACE b/NAMESPACE index 1b0b85a..933cfc1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -39,6 +39,10 @@ exportMethods("coerce", "show", "htmlDoc", "htmlValue", "htmlFilename") export("writeBiocViews", "getBiocViews", "write_VIEWS", "write_REPOSITORY", "genReposControlFiles", "extractVignettes", "extractManuals", + ## html manual functions + "build_db_from_source", "build_meta_aliases_db", + "build_meta_rdxrefs_db", "build_html_mans", + ## "extractCitations", "getCurrentbiocViews", "extractNEWS", "extractHTMLDocuments", "extractTopLevelFiles", "writeRepositoryHtml", "writePackageDetailHtml", "getSubTerms", diff --git a/R/build_html_mans.R b/R/build_html_mans.R index ae850e9..8ea6e69 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -6,8 +6,8 @@ #' @param package_dir `character(1)` The local path to a package for which to #' build the aliases and cross-ref databases (`rds` files). #' -#' @param src_base `character(1)` The path to the base hosting directory for the -#' package repository. This is typically a location on the BBS server. +#' @param src_destDir `character(1)` The path to the base hosting directory for +#' the package repository. This is typically a location on the BBS server. #' #' @examples #' if (interactive()) { @@ -20,17 +20,17 @@ #' #' ## generate from Bioc package source dirs #' packages <- file.path(normalizePath("~/bioc"), bioc_sub) -#' src_base <- "~/minibioc/packages/3.20/bioc" +#' src_destDir <- "~/minibioc/packages/3.20/bioc" #' #' for (package in packages) { -#' build_db_from_source(package, src_base) +#' build_db_from_source(package, src_destDir) #' } #' } #' @export -build_db_from_source <- function(package_dir, src_base) { +build_db_from_source <- function(package_dir, src_destDir) { tmp_dir <- tempdir() package <- basename(package_dir) - package_web_dir <- file.path(src_base, "web", "packages", package) + package_web_dir <- file.path(src_destDir, "web", "packages", package) if (!dir.exists(package_web_dir)) dir.create(package_web_dir, recursive = TRUE) db <- tools::Rd_db(dir = package_dir) @@ -75,10 +75,10 @@ build_db_from_source <- function(package_dir, src_base) { #' #' @examples #' if (interactive()) { -#' src_base <- "~/minibioc/packages/3.20/bioc/" -#' web_dir <- file.path(src_base, "web", "packages") +#' src_destDir <- "~/minibioc/packages/3.20/bioc/" +#' web_dir <- file.path(src_destDir, "web", "packages") #' -#' meta_folder <- file.path(contrib.url(src_base), "Meta") +#' meta_folder <- file.path(contrib.url(src_destDir), "Meta") #' if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) #' aliases_db_file <- file.path(meta_folder, "aliases.rds") #' @@ -118,10 +118,10 @@ is_file <- function(x) file.exists(x) && !file.info(x)[["isdir"]] #' #' @examples #' if (interactive()) { -#' src_base <- "~/minibioc/packages/3.20/bioc/" -#' web_dir <- file.path(src_base, "web", "packages") +#' src_destDir <- "~/minibioc/packages/3.20/bioc/" +#' web_dir <- file.path(src_destDir, "web", "packages") #' -#' meta_folder <- file.path(contrib.url(src_base), "Meta") +#' meta_folder <- file.path(contrib.url(src_destDir), "Meta") #' if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) #' rdxrefs_db_file <- file.path(meta_folder, "rdxrefs.rds") #' @@ -167,14 +167,14 @@ build_meta_rdxrefs_db <- #' #' ## generate from Bioc package source dirs #' packages <- file.path(normalizePath("~/bioc"), bioc_sub) -#' src_base <- "~/minibioc/packages/3.20/bioc" +#' src_destDir <- "~/minibioc/packages/3.20/bioc" #' -#' build_html_mans(packages, src_base) +#' build_html_mans(packages, src_destDir) #' } #' @export -build_html_mans <- function(package_dirs, src_base) { +build_html_mans <- function(package_dirs, src_destDir) { packages <- basename(package_dirs) - man_dir <- file.path(src_base, "manuals") + man_dir <- file.path(src_destDir, "manuals") if (!dir.exists(man_dir)) dir.create(man_dir, recursive = TRUE) outfiles <- file.path(man_dir, packages, "man", paste0(packages, ".html")) for (i in seq_along(package_dirs)) { diff --git a/man/html-manuals.Rd b/man/html-manuals.Rd index 15ab7eb..cecb83a 100644 --- a/man/html-manuals.Rd +++ b/man/html-manuals.Rd @@ -8,20 +8,20 @@ \alias{build_html_mans} \title{Helper functions to generate HTML pages for reference manuals} \usage{ -build_db_from_source(package_dir, src_base) +build_db_from_source(package_dir, src_destDir) build_meta_aliases_db(web_dir, aliases_db_file, force = FALSE) build_meta_rdxrefs_db(web_dir, rdxrefs_db_file, force = FALSE) -build_html_mans(package_dirs, src_base) +build_html_mans(package_dirs, src_destDir) } \arguments{ \item{package_dir}{`character(1)` The local path to a package for which to build the aliases and cross-ref databases (`rds` files).} -\item{src_base}{`character(1)` The path to the base hosting directory for the -package repository. This is typically a location on the BBS server.} +\item{src_destDir}{`character(1)` The path to the base hosting directory for +the package repository. This is typically a location on the BBS server.} \item{web_dir}{`character(1)` The `web/packages` local directory that is also hosted on the website e.g., for CRAN @@ -53,17 +53,17 @@ if (interactive()) { ## generate from Bioc package source dirs packages <- file.path(normalizePath("~/bioc"), bioc_sub) - src_base <- "~/minibioc/packages/3.20/bioc" + src_destDir <- "~/minibioc/packages/3.20/bioc" for (package in packages) { - build_db_from_source(package, src_base) + build_db_from_source(package, src_destDir) } } if (interactive()) { - src_base <- "~/minibioc/packages/3.20/bioc/" - web_dir <- file.path(src_base, "web", "packages") + src_destDir <- "~/minibioc/packages/3.20/bioc/" + web_dir <- file.path(src_destDir, "web", "packages") - meta_folder <- file.path(contrib.url(src_base), "Meta") + meta_folder <- file.path(contrib.url(src_destDir), "Meta") if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) aliases_db_file <- file.path(meta_folder, "aliases.rds") @@ -72,10 +72,10 @@ if (interactive()) { saveRDS(meta_aliases_db, aliases_db_file, version = 2) } if (interactive()) { - src_base <- "~/minibioc/packages/3.20/bioc/" - web_dir <- file.path(src_base, "web", "packages") + src_destDir <- "~/minibioc/packages/3.20/bioc/" + web_dir <- file.path(src_destDir, "web", "packages") - meta_folder <- file.path(contrib.url(src_base), "Meta") + meta_folder <- file.path(contrib.url(src_destDir), "Meta") if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) rdxrefs_db_file <- file.path(meta_folder, "rdxrefs.rds") @@ -93,8 +93,8 @@ if (interative()) { ## generate from Bioc package source dirs packages <- file.path(normalizePath("~/bioc"), bioc_sub) - src_base <- "~/minibioc/packages/3.20/bioc" + src_destDir <- "~/minibioc/packages/3.20/bioc" - build_html_mans(packages, src_base) + build_html_mans(packages, src_destDir) } } From b2d870a26e4f47eb6cccfc10e4adc5441eb801ef Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Tue, 19 Nov 2024 07:21:25 -1000 Subject: [PATCH 04/10] rename to reposRoot --- R/build_html_mans.R | 30 +++++++++++++++--------------- man/html-manuals.Rd | 26 +++++++++++++------------- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/R/build_html_mans.R b/R/build_html_mans.R index 8ea6e69..aaddda6 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -6,7 +6,7 @@ #' @param package_dir `character(1)` The local path to a package for which to #' build the aliases and cross-ref databases (`rds` files). #' -#' @param src_destDir `character(1)` The path to the base hosting directory for +#' @param reposRoot `character(1)` The path to the base hosting directory for #' the package repository. This is typically a location on the BBS server. #' #' @examples @@ -20,17 +20,17 @@ #' #' ## generate from Bioc package source dirs #' packages <- file.path(normalizePath("~/bioc"), bioc_sub) -#' src_destDir <- "~/minibioc/packages/3.20/bioc" +#' reposRoot <- "~/minibioc/packages/3.20/bioc" #' #' for (package in packages) { -#' build_db_from_source(package, src_destDir) +#' build_db_from_source(package, reposRoot) #' } #' } #' @export -build_db_from_source <- function(package_dir, src_destDir) { +build_db_from_source <- function(package_dir, reposRoot) { tmp_dir <- tempdir() package <- basename(package_dir) - package_web_dir <- file.path(src_destDir, "web", "packages", package) + package_web_dir <- file.path(reposRoot, "web", "packages", package) if (!dir.exists(package_web_dir)) dir.create(package_web_dir, recursive = TRUE) db <- tools::Rd_db(dir = package_dir) @@ -75,10 +75,10 @@ build_db_from_source <- function(package_dir, src_destDir) { #' #' @examples #' if (interactive()) { -#' src_destDir <- "~/minibioc/packages/3.20/bioc/" -#' web_dir <- file.path(src_destDir, "web", "packages") +#' reposRoot <- "~/minibioc/packages/3.20/bioc/" +#' web_dir <- file.path(reposRoot, "web", "packages") #' -#' meta_folder <- file.path(contrib.url(src_destDir), "Meta") +#' meta_folder <- file.path(contrib.url(reposRoot), "Meta") #' if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) #' aliases_db_file <- file.path(meta_folder, "aliases.rds") #' @@ -118,10 +118,10 @@ is_file <- function(x) file.exists(x) && !file.info(x)[["isdir"]] #' #' @examples #' if (interactive()) { -#' src_destDir <- "~/minibioc/packages/3.20/bioc/" -#' web_dir <- file.path(src_destDir, "web", "packages") +#' reposRoot <- "~/minibioc/packages/3.20/bioc/" +#' web_dir <- file.path(reposRoot, "web", "packages") #' -#' meta_folder <- file.path(contrib.url(src_destDir), "Meta") +#' meta_folder <- file.path(contrib.url(reposRoot), "Meta") #' if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) #' rdxrefs_db_file <- file.path(meta_folder, "rdxrefs.rds") #' @@ -167,14 +167,14 @@ build_meta_rdxrefs_db <- #' #' ## generate from Bioc package source dirs #' packages <- file.path(normalizePath("~/bioc"), bioc_sub) -#' src_destDir <- "~/minibioc/packages/3.20/bioc" +#' reposRoot <- "~/minibioc/packages/3.20/bioc" #' -#' build_html_mans(packages, src_destDir) +#' build_html_mans(packages, reposRoot) #' } #' @export -build_html_mans <- function(package_dirs, src_destDir) { +build_html_mans <- function(package_dirs, reposRoot) { packages <- basename(package_dirs) - man_dir <- file.path(src_destDir, "manuals") + man_dir <- file.path(reposRoot, "manuals") if (!dir.exists(man_dir)) dir.create(man_dir, recursive = TRUE) outfiles <- file.path(man_dir, packages, "man", paste0(packages, ".html")) for (i in seq_along(package_dirs)) { diff --git a/man/html-manuals.Rd b/man/html-manuals.Rd index cecb83a..34d15fa 100644 --- a/man/html-manuals.Rd +++ b/man/html-manuals.Rd @@ -8,19 +8,19 @@ \alias{build_html_mans} \title{Helper functions to generate HTML pages for reference manuals} \usage{ -build_db_from_source(package_dir, src_destDir) +build_db_from_source(package_dir, reposRoot) build_meta_aliases_db(web_dir, aliases_db_file, force = FALSE) build_meta_rdxrefs_db(web_dir, rdxrefs_db_file, force = FALSE) -build_html_mans(package_dirs, src_destDir) +build_html_mans(package_dirs, reposRoot) } \arguments{ \item{package_dir}{`character(1)` The local path to a package for which to build the aliases and cross-ref databases (`rds` files).} -\item{src_destDir}{`character(1)` The path to the base hosting directory for +\item{reposRoot}{`character(1)` The path to the base hosting directory for the package repository. This is typically a location on the BBS server.} \item{web_dir}{`character(1)` The `web/packages` local directory that is @@ -53,17 +53,17 @@ if (interactive()) { ## generate from Bioc package source dirs packages <- file.path(normalizePath("~/bioc"), bioc_sub) - src_destDir <- "~/minibioc/packages/3.20/bioc" + reposRoot <- "~/minibioc/packages/3.20/bioc" for (package in packages) { - build_db_from_source(package, src_destDir) + build_db_from_source(package, reposRoot) } } if (interactive()) { - src_destDir <- "~/minibioc/packages/3.20/bioc/" - web_dir <- file.path(src_destDir, "web", "packages") + reposRoot <- "~/minibioc/packages/3.20/bioc/" + web_dir <- file.path(reposRoot, "web", "packages") - meta_folder <- file.path(contrib.url(src_destDir), "Meta") + meta_folder <- file.path(contrib.url(reposRoot), "Meta") if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) aliases_db_file <- file.path(meta_folder, "aliases.rds") @@ -72,10 +72,10 @@ if (interactive()) { saveRDS(meta_aliases_db, aliases_db_file, version = 2) } if (interactive()) { - src_destDir <- "~/minibioc/packages/3.20/bioc/" - web_dir <- file.path(src_destDir, "web", "packages") + reposRoot <- "~/minibioc/packages/3.20/bioc/" + web_dir <- file.path(reposRoot, "web", "packages") - meta_folder <- file.path(contrib.url(src_destDir), "Meta") + meta_folder <- file.path(contrib.url(reposRoot), "Meta") if (!dir.exists(meta_folder)) dir.create(meta_folder, recursive = TRUE) rdxrefs_db_file <- file.path(meta_folder, "rdxrefs.rds") @@ -93,8 +93,8 @@ if (interative()) { ## generate from Bioc package source dirs packages <- file.path(normalizePath("~/bioc"), bioc_sub) - src_destDir <- "~/minibioc/packages/3.20/bioc" + reposRoot <- "~/minibioc/packages/3.20/bioc" - build_html_mans(packages, src_destDir) + build_html_mans(packages, reposRoot) } } From 797ed9aef188a7e5c4d550be71843f8c2609d13b Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Tue, 19 Nov 2024 07:22:24 -1000 Subject: [PATCH 05/10] add details section --- R/build_html_mans.R | 21 +++++++++++++++++++++ man/html-manuals.Rd | 21 +++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/R/build_html_mans.R b/R/build_html_mans.R index aaddda6..b411d9d 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -9,6 +9,27 @@ #' @param reposRoot `character(1)` The path to the base hosting directory for #' the package repository. This is typically a location on the BBS server. #' +#' @details +#' These functions are used to generate the `aliases.rds` and `rdxrefs.rds` +#' files for each package. These files are used to generate a metadata database +#' `Rds` file via the `build_meta_aliases_db` and `build_meta_rdxrefs_db` +#' functions for all packages. The `aliases.rds` file is a list of aliases +#' within each `.Rd` page in the package. The `rdxrefs.rds` file is a matrix of +#' cross-references between an external topic and the originating `.Rd` page. +#' The individual package databases are then combined into a single database +#' file for the entire repository. Each package's database is stored in the +#' `web/packages` directory in `reposRoot`. The collective metadata database +#' files are stored in the `src/contrib/Meta` directory in `reposRoot`. +#' +#' The alias and cross-reference files are generated from the package source +#' directory but may also be generated from a built package tarball +#' (functionality not included). The code is meant to run on the BBS, typically +#' after a package has been built or updated. +#' +#' The `build_html_mans` function is used to generate the HTML manuals for each +#' package. These pages will be hosted on the BBS server and linked in the +#' package landing page. +#' #' @examples #' if (interactive()) { #' library(BiocPkgTools) diff --git a/man/html-manuals.Rd b/man/html-manuals.Rd index 34d15fa..2e03a1a 100644 --- a/man/html-manuals.Rd +++ b/man/html-manuals.Rd @@ -42,6 +42,27 @@ generated by the `build_db_from_source` function.} \description{ Helper functions to generate HTML pages for reference manuals } +\details{ +These functions are used to generate the `aliases.rds` and `rdxrefs.rds` +files for each package. These files are used to generate a metadata database +`Rds` file via the `build_meta_aliases_db` and `build_meta_rdxrefs_db` +functions for all packages. The `aliases.rds` file is a list of aliases +within each `.Rd` page in the package. The `rdxrefs.rds` file is a matrix of +cross-references between an external topic and the originating `.Rd` page. +The individual package databases are then combined into a single database +file for the entire repository. Each package's database is stored in the +`web/packages` directory in `reposRoot`. The collective metadata database +files are stored in the `src/contrib/Meta` directory in `reposRoot`. + +The alias and cross-reference files are generated from the package source +directory but may also be generated from a built package tarball +(functionality not included). The code is meant to run on the BBS, typically +after a package has been built or updated. + +The `build_html_mans` function is used to generate the HTML manuals for each +package. These pages will be hosted on the BBS server and linked in the +package landing page. +} \examples{ if (interactive()) { library(BiocPkgTools) From 0dd2e2dc605df99ef3e2d5bd04f15e73249223fa Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Tue, 19 Nov 2024 07:22:51 -1000 Subject: [PATCH 06/10] specify source package dirs --- R/build_html_mans.R | 3 ++- man/html-manuals.Rd | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/R/build_html_mans.R b/R/build_html_mans.R index b411d9d..3c78f60 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -175,7 +175,8 @@ build_meta_rdxrefs_db <- #' @rdname html-manuals #' -#' @param package_dirs `character()` A vector of local package directories. +#' @param package_dirs `character()` A vector of local source package +#' directories. #' #' @examples #' if (interative()) { diff --git a/man/html-manuals.Rd b/man/html-manuals.Rd index 2e03a1a..faa56ea 100644 --- a/man/html-manuals.Rd +++ b/man/html-manuals.Rd @@ -37,7 +37,8 @@ database file. If `TRUE`, the function will read all aliases/rdxrefs files.} \item{rdxrefs_db_file}{`character(1)` The file path to `rdxrefs.rds` file generated by the `build_db_from_source` function.} -\item{package_dirs}{`character()` A vector of local package directories.} +\item{package_dirs}{`character()` A vector of local source package +directories.} } \description{ Helper functions to generate HTML pages for reference manuals From c519667c0f17f40ca89a26060ec0a48b736c64bb Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Tue, 19 Nov 2024 07:24:11 -1000 Subject: [PATCH 07/10] create manuals/pkg/man/ dir --- R/build_html_mans.R | 3 +++ 1 file changed, 3 insertions(+) diff --git a/R/build_html_mans.R b/R/build_html_mans.R index 3c78f60..67f2042 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -199,7 +199,10 @@ build_html_mans <- function(package_dirs, reposRoot) { man_dir <- file.path(reposRoot, "manuals") if (!dir.exists(man_dir)) dir.create(man_dir, recursive = TRUE) outfiles <- file.path(man_dir, packages, "man", paste0(packages, ".html")) + outdirs <- dirname(outfiles) for (i in seq_along(package_dirs)) { + if (!dir.exists(outdirs[i])) + dir.create(outdirs[i], recursive = TRUE) tools::pkg2HTML( dir = package_dirs[i], out = outfiles[i] From 8bae534b69a6371de607b39bc1492c36ff0fc1fb Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Thu, 6 Feb 2025 17:58:09 -0500 Subject: [PATCH 08/10] use hooks to link to appropriate package HTML page --- R/build_html_mans.R | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/R/build_html_mans.R b/R/build_html_mans.R index 67f2042..efce3f4 100644 --- a/R/build_html_mans.R +++ b/R/build_html_mans.R @@ -205,7 +205,15 @@ build_html_mans <- function(package_dirs, reposRoot) { dir.create(outdirs[i], recursive = TRUE) tools::pkg2HTML( dir = package_dirs[i], - out = outfiles[i] + out = outfiles[i], + hooks = list( + pkg_href = function(pkg) { + sprintf( + "../../%s/man/%s.html", + pkg, pkg + ) + } + ) ) } outfiles From c814ffd3b96bfba300bec58e96b5300b4463a5b0 Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Sat, 24 May 2025 10:31:06 -0400 Subject: [PATCH 09/10] rename build_html_mans to build_dbs --- DESCRIPTION | 4 +- NAMESPACE | 5 +-- R/{build_html_mans.R => build_dbs.R} | 53 ++------------------------- man/{html-manuals.Rd => build-dbs.Rd} | 26 ++----------- 4 files changed, 10 insertions(+), 78 deletions(-) rename R/{build_html_mans.R => build_dbs.R} (81%) rename man/{html-manuals.Rd => build-dbs.Rd} (85%) diff --git a/DESCRIPTION b/DESCRIPTION index 37d2f79..34993cc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -19,12 +19,12 @@ Maintainer: Bioconductor Package Maintainer Depends: R (>= 3.6.0) Imports: Biobase, graph (>= 1.9.26), methods, RBGL (>= 1.13.5), tools, utils, XML, RCurl, RUnit, BiocManager -Suggests: BiocGenerics, knitr, commonmark, BiocStyle +Suggests: BiocGenerics, BiocPkgTools, knitr, commonmark, BiocStyle Collate: AllClasses.R AllGenerics.R as-methods.R htmlDoc-methods.R htmlFilename-methods.R htmlValue-methods.R show-methods.R getPackNames.R packageDetails.R pump.R repository.R showvoc.R getPackageNEWS.R validation_tests.R recommendBiocViews.R - dump_concept.R build_html_mans.R + dump_concept.R build_dbs.R VignetteBuilder: knitr RoxygenNote: 7.3.2 Encoding: UTF-8 diff --git a/NAMESPACE b/NAMESPACE index 933cfc1..f0c1160 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -39,9 +39,8 @@ exportMethods("coerce", "show", "htmlDoc", "htmlValue", "htmlFilename") export("writeBiocViews", "getBiocViews", "write_VIEWS", "write_REPOSITORY", "genReposControlFiles", "extractVignettes", "extractManuals", - ## html manual functions - "build_db_from_source", "build_meta_aliases_db", - "build_meta_rdxrefs_db", "build_html_mans", + ## build db functions + "build_db_from_source", "build_meta_aliases_db", "build_meta_rdxrefs_db", ## "extractCitations", "getCurrentbiocViews", "extractNEWS", "extractHTMLDocuments", "extractTopLevelFiles", diff --git a/R/build_html_mans.R b/R/build_dbs.R similarity index 81% rename from R/build_html_mans.R rename to R/build_dbs.R index efce3f4..308888d 100644 --- a/R/build_html_mans.R +++ b/R/build_dbs.R @@ -1,5 +1,4 @@ - -#' @name html-manuals +#' @name build-dbs #' #' @title Helper functions to generate HTML pages for reference manuals #' @@ -81,7 +80,7 @@ build_db_from_source <- function(package_dir, reposRoot) { message(xtofile) } -#' @rdname html-manuals +#' @rdname build-dbs #' #' @param web_dir `character(1)` The `web/packages` local directory that is #' also hosted on the website e.g., for CRAN @@ -132,7 +131,7 @@ build_meta_aliases_db <- is_file <- function(x) file.exists(x) && !file.info(x)[["isdir"]] -#' @rdname html-manuals +#' @rdname build-dbs #' #' @param rdxrefs_db_file `character(1)` The file path to `rdxrefs.rds` file #' generated by the `build_db_from_source` function. @@ -172,49 +171,3 @@ build_meta_rdxrefs_db <- db[sort(names(db))] } - -#' @rdname html-manuals -#' -#' @param package_dirs `character()` A vector of local source package -#' directories. -#' -#' @examples -#' if (interative()) { -#' library(BiocPkgTools) -#' bioc_sub <- pkgBiocDeps( -#' "SummarizedExperiment", pkgType = "software", -#' recursive = TRUE, only.bioc = TRUE -#' ) -#' bioc_sub <- unlist(bioc_sub, use.names = FALSE) -#' -#' ## generate from Bioc package source dirs -#' packages <- file.path(normalizePath("~/bioc"), bioc_sub) -#' reposRoot <- "~/minibioc/packages/3.20/bioc" -#' -#' build_html_mans(packages, reposRoot) -#' } -#' @export -build_html_mans <- function(package_dirs, reposRoot) { - packages <- basename(package_dirs) - man_dir <- file.path(reposRoot, "manuals") - if (!dir.exists(man_dir)) dir.create(man_dir, recursive = TRUE) - outfiles <- file.path(man_dir, packages, "man", paste0(packages, ".html")) - outdirs <- dirname(outfiles) - for (i in seq_along(package_dirs)) { - if (!dir.exists(outdirs[i])) - dir.create(outdirs[i], recursive = TRUE) - tools::pkg2HTML( - dir = package_dirs[i], - out = outfiles[i], - hooks = list( - pkg_href = function(pkg) { - sprintf( - "../../%s/man/%s.html", - pkg, pkg - ) - } - ) - ) - } - outfiles -} diff --git a/man/html-manuals.Rd b/man/build-dbs.Rd similarity index 85% rename from man/html-manuals.Rd rename to man/build-dbs.Rd index faa56ea..d2b421e 100644 --- a/man/html-manuals.Rd +++ b/man/build-dbs.Rd @@ -1,11 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/build_html_mans.R -\name{html-manuals} -\alias{html-manuals} +% Please edit documentation in R/build_dbs.R +\name{build-dbs} +\alias{build-dbs} \alias{build_db_from_source} \alias{build_meta_aliases_db} \alias{build_meta_rdxrefs_db} -\alias{build_html_mans} \title{Helper functions to generate HTML pages for reference manuals} \usage{ build_db_from_source(package_dir, reposRoot) @@ -13,8 +12,6 @@ build_db_from_source(package_dir, reposRoot) build_meta_aliases_db(web_dir, aliases_db_file, force = FALSE) build_meta_rdxrefs_db(web_dir, rdxrefs_db_file, force = FALSE) - -build_html_mans(package_dirs, reposRoot) } \arguments{ \item{package_dir}{`character(1)` The local path to a package for which to @@ -36,9 +33,6 @@ database file. If `TRUE`, the function will read all aliases/rdxrefs files.} \item{rdxrefs_db_file}{`character(1)` The file path to `rdxrefs.rds` file generated by the `build_db_from_source` function.} - -\item{package_dirs}{`character()` A vector of local source package -directories.} } \description{ Helper functions to generate HTML pages for reference manuals @@ -105,18 +99,4 @@ if (interactive()) { saveRDS(meta_rdxrefs_db, rdxrefs_db_file, version = 2) } -if (interative()) { - library(BiocPkgTools) - bioc_sub <- pkgBiocDeps( - "SummarizedExperiment", pkgType = "software", - recursive = TRUE, only.bioc = TRUE - ) - bioc_sub <- unlist(bioc_sub, use.names = FALSE) - - ## generate from Bioc package source dirs - packages <- file.path(normalizePath("~/bioc"), bioc_sub) - reposRoot <- "~/minibioc/packages/3.20/bioc" - - build_html_mans(packages, reposRoot) -} } From dffadd31b6a7b0e39ad188a1c99966fef8f9aca2 Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Thu, 29 May 2025 11:36:16 -0400 Subject: [PATCH 10/10] remove build_html_mans section in doc --- R/build_dbs.R | 4 ---- 1 file changed, 4 deletions(-) diff --git a/R/build_dbs.R b/R/build_dbs.R index 308888d..861c8a1 100644 --- a/R/build_dbs.R +++ b/R/build_dbs.R @@ -25,10 +25,6 @@ #' (functionality not included). The code is meant to run on the BBS, typically #' after a package has been built or updated. #' -#' The `build_html_mans` function is used to generate the HTML manuals for each -#' package. These pages will be hosted on the BBS server and linked in the -#' package landing page. -#' #' @examples #' if (interactive()) { #' library(BiocPkgTools)