From 26d15464d924706c811e490bd653242e5f6ac02f Mon Sep 17 00:00:00 2001 From: maksymis <32574056+maksymiuks@users.noreply.github.com> Date: Fri, 18 Oct 2024 18:20:35 +0200 Subject: [PATCH] Refine how macros are discovered --- DESCRIPTION | 4 ++-- NEWS.md | 6 ++++++ R/documentation_to_markdown.R | 7 ++++--- R/get_rd.R | 22 ++++++++++++++++------ R/utils.R | 10 ++++++++++ man/documentation_to_markdown.Rd | 2 +- man/get_rd.Rd | 2 +- tests/testthat/test-get_rd.R | 5 +++-- 8 files changed, 43 insertions(+), 15 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 4817470..3c6b05a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: rd2markdown Title: Convert Rd Files into Markdown -Version: 0.0.9 +Version: 0.1.0 Authors@R: c( person( @@ -40,4 +40,4 @@ License: MIT + file LICENSE VignetteBuilder: knitr Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.2 diff --git a/NEWS.md b/NEWS.md index 902e40f..1f984c9 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,9 @@ +rd2markdown 0.1.0 +----------------- + +* Add `find_package_root` helper and rebuild how the package discovers + default macros locations. + rd2markdown 0.0.9 ----------------- diff --git a/R/documentation_to_markdown.R b/R/documentation_to_markdown.R index bcde97e..2fddf3a 100644 --- a/R/documentation_to_markdown.R +++ b/R/documentation_to_markdown.R @@ -7,7 +7,7 @@ #' output list. Use \code{fragments} parameter whenever you want to limit #' extracted documentation only to some parts. #' -#' @param rdfilepaths A character vector of Rd documentation file paths +#' @param rdfilepaths A character vector of Rd documentation file paths. #' @inheritParams rd2markdown #' #' @return A named list of character vectors of length one with the markdown content. @@ -28,8 +28,9 @@ #' fragments = c("details")) #' #' @seealso \code{\link[rd2markdown]{rd2markdown}} \code{\link[rd2markdown]{get_rd}} -documentation_to_markdown <- function(rdfilepaths, - fragments = c("title", "usage", "description", "details")) { +documentation_to_markdown <- function( + rdfilepaths, + fragments = c("title", "usage", "description", "details")) { rds <- mapply(get_rd, file = rdfilepaths, SIMPLIFY = FALSE) max_n <- nchar(length(rdfilepaths)) diff --git a/R/get_rd.R b/R/get_rd.R index 801000e..02d4726 100644 --- a/R/get_rd.R +++ b/R/get_rd.R @@ -33,18 +33,28 @@ DEFAULT_R_MACROS <- file.path(R.home("share"), "Rd", "macros", "system.Rd") #' rd2markdown::get_rd(file = rd_file_example, macros = NA) #' #' @export -get_rd <- function(topic, package, file = NULL, macros = DEFAULT_R_MACROS) { +get_rd <- function( + topic, + package, + file = NULL, + # Deafult R macros location defined in R documentation + macros = NULL) { if (!is.null(file)) { - potential_macros <- list.files(file.path(dirname(file), "macros"), pattern = "\\.Rd$|\\.rd$") - if (!is.null(macros) && is.na(macros) && length(potential_macros) > 0) { - # Extract first element as tools::parse_Rd accepts only a single file - macros <- file.path(dirname(file), "macros", potential_macros)[1] + macros <- if (is.null(macros) && (root <- find_package_root(file)) != "") { + tools::loadPkgRdMacros(root) + } else if (is.null(macros)) { + tools::loadRdMacros(DEFAULT_R_MACROS) + } else if (!is.null(macros) && is.character(macros)) { + tools::loadRdMacros(macros) + } else { + macros } + rd <- tools::parse_Rd(file = file, permissive = TRUE, macros = macros) .tools$processRdSexprs( rd, stage = "render", - macros = tools::loadRdMacros(DEFAULT_R_MACROS) + macros = tools::loadRdMacros(DEFAULT_R_MACROS, macros = macros) ) } else { tryCatch({ diff --git a/R/utils.R b/R/utils.R index fe7b2e1..dad0717 100644 --- a/R/utils.R +++ b/R/utils.R @@ -9,3 +9,13 @@ vcapply <- function(..., FUN.VALUE = character(1L)) { triml <- function(x, ..., which = "left") { trimws(x, ...) } + +find_package_root <- function(file, depth = 3) { + if (depth == 0) { + "" + } else if (!file.exists(file.path(dirname(file), "DESCRIPTION"))) { + find_package_root(dirname(file), depth - 1) + } else { + dirname(file) + } +} diff --git a/man/documentation_to_markdown.Rd b/man/documentation_to_markdown.Rd index 27219cc..0e108c5 100644 --- a/man/documentation_to_markdown.Rd +++ b/man/documentation_to_markdown.Rd @@ -10,7 +10,7 @@ documentation_to_markdown( ) } \arguments{ -\item{rdfilepaths}{A character vector of Rd documentation file paths} +\item{rdfilepaths}{A character vector of Rd documentation file paths.} \item{fragments}{An optional vector of fragment tag names (such as "description", "details" or "title") to filter the Rd object tags.} diff --git a/man/get_rd.Rd b/man/get_rd.Rd index e3a1edf..4a3f8ee 100644 --- a/man/get_rd.Rd +++ b/man/get_rd.Rd @@ -4,7 +4,7 @@ \alias{get_rd} \title{Safely retrieve help documentation objects} \usage{ -get_rd(topic, package, file = NULL, macros = DEFAULT_R_MACROS) +get_rd(topic, package, file = NULL, macros = NULL) } \arguments{ \item{topic}{usually, a \link{name} or character string specifying the diff --git a/tests/testthat/test-get_rd.R b/tests/testthat/test-get_rd.R index e599786..cc33f33 100644 --- a/tests/testthat/test-get_rd.R +++ b/tests/testthat/test-get_rd.R @@ -12,8 +12,9 @@ test_that("Can find relevant R documentation files, given a .Rd filepath", { test_that("get_rd find macros properly", { rd_filepath <- system.file("examples", "rd_file_sample_2.Rd", package = "rd2markdown") - expect_s3_class(get_rd(file = rd_filepath, macros = NA), "Rd") - expect_silent(rd <- get_rd(file = rd_filepath, macros = NA)) + rd_macro <- system.file("examples", "macros", "macros.Rd", package = "rd2markdown") + expect_s3_class(get_rd(file = rd_filepath, macros = rd_macro), "Rd") + expect_silent(rd <- get_rd(file = rd_filepath, macros = rd_macro)) expect_equivalent( rd[[17]][[3]], structure(c("\\code{\\link[=#1]{#1()}}", "rnorm"), Rd_tag = "USERMACRO", macro = "\\function")