Документация по объекту R: пакетная документация в качестве первого элемента

У меня есть пакет R, и я хочу отобразить общую информацию о пакете в качестве первого элемента в созданном руководстве в формате PDF.

Я использую roxygen2 (версия 7.0.2) для создания документации и следую приведенным инструкциям здесь. Когда я создаю документацию, все элементы, появляющиеся в руководстве, упорядочены в алфавитном порядке, включая элемент общей документации. Но, конечно, я хочу, чтобы общая документация была наверху.

Кажется, что размещение элемента документации пакета первым должно как-то работать, потому что это работает в руководство по вязанию.

Моя установка: я создал пакет «TestPackage» с помощью RStudio с одним файлом «hello.R»:

#' Hello world function
#'
#' Prints "Hello, world!"
#'
#'@return nothing interesting
hello <- function() {
  print("Hello, world!")
}

и один файл «TestPackage.R» с общей документацией по пакету.

#' A test package
#'
#' @docType package
#' @name TestPackage
NULL

Когда я бегу,

R CMD Rd2pdf TestPackage

Я получаю руководство в формате PDF с первым пунктом «привет», а затем пунктом «TestPackage».

Как я могу добиться, чтобы элемент для пакета был первым?


r roxygen2 documentation-generation
person esel    schedule 31.12.2019    source источник
comment
Можете ли вы попробовать изменить строку #' @name TestPackage на #' @name TestPackage-package?   -  person duckmayr    schedule 31.12.2019
comment
Безумие! Спасибо, это работает! Если вы опубликуете это как ответ, я могу принять его. Хотя это работает, я также был бы признателен за некоторую справочную информацию о том, почему это работает, если вы можете дать ее.   -  person esel    schedule 01.01.2020
comment
Те инструкции, которые вы цитируете, немного устарели. Вместо этого смотрите здесь: cran.r-project.org/ веб/пакеты/roxygen2/виньетки/   -  person user2554330    schedule 01.01.2020

Ответы (1)


arrow_upward
2
arrow_downward

Чтобы гарантировать, что запись документации пакета будет первой в руководстве, вам нужно, чтобы ее name было <packagename>-package (где вы заменяете <packagename> именем вашего пакета). Здесь вы можете сделать это, изменив

#' @name TestPackage

to

#' @name TestPackage-package

Почему это так? Что ж, как всегда, когда вы сталкиваетесь с каким-то странным уголком разработки пакета R, лучшее, что вы можете сделать, это обратиться к Написание руководства по расширениям R. Здесь мы хотели бы взглянуть на Раздел 2.1, формат Rd (файлы документации в R имеют формат Rd; roxygen создает для вас Rd файлы в man/). В частности, в разделе 2.1.1 мы видим

\имя{имя}

name обычно101 — это базовое имя Rd-файла, содержащего документацию. ... Записи в руководстве по пакету будут располагаться в алфавитном порядке102 от записей \name.

Эта сноска 102 говорит нам

в текущей локали, со специальной обработкой специальных символов LaTeX и с любой темой «pkgname-package», перемещенной в начало списка.

Итак, вам нужно name файл Rd как pkgname-package, чтобы переместить его в начало руководства.

person duckmayr    schedule 01.01.2020
comment
Я думаю, что это происходит автоматически, если вы используете дозорный _PACKAGE, описанный в виньетке тегов Rd (документация) в roxygen2. - person user2554330; 01.01.2020
comment
Может быть, вы можете уточнить это? Как я могу использовать этот часовой? - person esel; 02.01.2020