Как запустить функции документации внутри roxygen2 @examples?
У меня есть множество подобных функций, в документации которых нужно изменить всего одно или два слова. Чтобы ограничить дублирование, я использую функции из документации.
Это работает в roxygen2 для @description и @param, но я не могу заставить его работать для @examples. Встроенный код не оценивается.
Пример
useless_description <- function(name) {
paste0('This useless function prints the word "', name , '" n times.')
}
useless_example <- function(name) {
paste("# Print ", name, " 1 time",
name, "(1)",
"",
"# Print ", name, " 3 times",
name, "(3)",
sep = "\n"
)
}
#' @title Hello
#' @description `r useless_description("hello")`
#' @examples `r useless_example("hello")`
hello <- function(n) {
print(rep("hello", n))
}
#' @title Goodbye
#' @description `r useless_description("goodbye")`
#' @examples `r useless_example("hello")`
goodbye <- function(n) {
print(rep("goodbye", n))
}
При запуске devtools::document() для функции hello() создается страница справки:
Возможное решение с помощью @eval
Я нашел способ обойти эту проблему, но он использует замененное ключевое слово @eval.
useless_example2 <- function(name) {
c("@examples ",
paste0("# Print ", name, " 1 time"),
paste0(name, "(1)"),
"",
paste0("# Print ", name, " 3 time"),
paste0(name, "(3)")
)
}
#' @title Hello
#' @description `r useless_description("hello")`
#' @eval useless_example2("hello")
hello <- function(n) {
print(rep("hello", n))
}
Итоговая страница справки:
Вопрос
Есть ли способ оценить встроенный код в roxygen2 @examples без использования замененных функций?
Если вы считаете, что пакет не работает так, как описано в документации, вам следует сообщить авторам о проблеме на github.
@VinceGreg, ты прав paste(); Я обновил пример. Однако я не могу воспроизвести ваш пример. Код работает для меня. Пожалуйста, откройте новый вопрос, тогда я постараюсь вам помочь.
@VinceGreg, ты добавил Roxygen: list(markdown = TRUE) в свой файл DESCRIPTION?
@the-mad-statter, ты был прав! После быстрого поиска я использовал альтернативу; usethis::use_roxygen_md() , как объяснено [в документе roxygen2] (roxygen2.r-lib.org/articles/rd-formatting.html)
Ответы 1
Прежде всего обратите внимание, что использование встроенного кода с {Roxygen2} работает только в том случае, если включена поддержка уценки. Это достигается либо:
- глобально, вставив
Roxygen: list(markdown = TRUE)в файл ОПИСАНИЯ пакета (например,usethis::use_roxygen_md()) или - локально, используя
@mdв текущем кислородном блоке
Как вы заметили, использование @eval было заменено в пользу встроенного кода R.
На той же странице авторы говорят:
Встроенная уценка R может генерировать текст уценки только внутри тега, поэтому в принципе она менее гибкая, чем @eval/@evalRd/@template. Однако наш опыт показал, что создание нескольких тегов одновременно имеет тенденцию быть довольно негибким, и вам часто приходится проводить рефакторинг на более мелкие части, поэтому мы не считаем, что это отражает реальную потерю функциональности.
Я вижу два момента, которые стоит повторить:
- Встроенная уценка/код R может генерироваться только для каждого тега.
- Авторы не заинтересованы в изменении такого поведения.
Тогда на этой странице авторы отмечают, что:
Некоторые теги roxygen не анализируются как уценка. Большинство из них вряд ли будут содержать текст, требующий разметки, поэтому это не является важным ограничением. Теги без поддержки уценки: @aliases, @backref, @docType, @encoding, @evalRd, @example, @examples, @family, @inheritParams, @keywords, @method @name, @md, @noMd, @noRd, @ rdname, @rawRd, @usage.
Вот почему ваш встроенный код работает для @description, но не работает для @examples, поскольку авторы пакета явно решили не поддерживать встроенный код для @examples.
Если вы хотите следовать замыслу авторов пакета и не использовать устаревшие функции, я предлагаю вам расширить {roxygen2} своим собственным тегом. Вы даже можете сделать так, чтобы ваш тег просто добавлялся к уже существующему разделу примеров.
Несмотря на то, что придется разобраться с некоторыми тонкостями, добавление собственного пользовательского тега может быть таким же простым, как определение двух таких функций:
roxy_tag_parse.roxy_tag_examples2 <- function(x) {
roxygen2::tag_markdown(x)
}
roxy_tag_rd.roxy_tag_examples2 <- function(x, base_path, env) {
roxygen2::rd_section("examples", x$val)
}
Затем загрузите эти функции в память перед документированием вашего пакета.
Вот пример файла пакета R:
roxygen_generate_description <- function(x) {
sprintf('This function prints the word "%s" n times.', x)
}
# a kink to workout:
# - use \u0023 for # to avoid an attempt at a level 1 header
roxygen_generate_examples <- function(x) {
paste(
sprintf("\u0023 Print %s 1 time", x),
sprintf("%s(1)", x),
"",
sprintf("\u0023 Print %s 3 times", x),
sprintf("%s(3)", x),
sep = "\n"
)
}
#' @title Hello
#' @description `r roxygen_generate_description("hello")`
#' @examples2 `r roxygen_generate_examples("hello")`
hello <- function(n) {
print(rep("hello", n))
}
И затем делаем:
devtools::document()
?hello
Мы получаем это:
Отличное объяснение и запись. Думаю, я попробую использовать @eval, поскольку он делает то же самое, но с гораздо меньшей сложностью.
Я новичок в разработке пакетов. Я не могу воспроизвести пример документа roxygen2.r-lib.org/articles/reuse.html#inline-code; Я вижу буквально «Название 'r 1 + 1'». Я мало чем могу помочь; за исключением того, что я заметил, что вы используете
paste0()сsep = "\n)"вuseless_example, что является формальным аргументом толькоpaste()(а неpaste0(). Я буду следить за этим постом.