Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refine how macros are discovered #37

Merged
merged 3 commits into from
Oct 23, 2024
Merged

Refine how macros are discovered #37

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26d1546
Refine how macros are discovered
maksymiuks Oct 18, 2024
aeb7ae5
Remove leftovers
maksymiuks Oct 18, 2024
32ddf01
Add discovery tests
maksymiuks Oct 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions DESCRIPTION
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Package: rd2markdown
Title: Convert Rd Files into Markdown
Version: 0.0.9
Version: 0.1.0
Authors@R:
c(
person(
Expand Down Expand Up @@ -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
6 changes: 6 additions & 0 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
-----------------

Expand Down
7 changes: 4 additions & 3 deletions R/documentation_to_markdown.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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))
Expand Down
22 changes: 16 additions & 6 deletions R/get_rd.R
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# constants
# Deafult R macros location defined in R documentation
DEFAULT_R_MACROS <- file.path(R.home("share"), "Rd", "macros", "system.Rd")

#' Safely retrieve help documentation objects
Expand Down Expand Up @@ -33,18 +34,27 @@ 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,
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({
Expand Down
10 changes: 10 additions & 0 deletions R/utils.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
2 changes: 1 addition & 1 deletion man/documentation_to_markdown.Rd
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/get_rd.Rd
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions tests/testthat/test-get_rd.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Comment on lines +15 to +17
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This test doesn't really test the discovery of package macros, which is a pretty central feature here. Can we also add a test for a macro we embed in this package?

You can see a trivial macro here in a package I was working on recently.

We could test it easily by using it in the package docs themselves or alternatively creating a tiny fixture package to test it against.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tests added!

expect_equivalent(
rd[[17]][[3]],
structure(c("\\code{\\link[=#1]{#1()}}", "rnorm"), Rd_tag = "USERMACRO", macro = "\\function")
Expand Down
Loading