Как вы пишете свою документацию по пакетам?

Я не совсем понял разумный рабочий процесс для создания пакетов и написания их документации.

Я хочу, чтобы как можно больше процессов (и документации) было создано автоматически.

Очевидным способом сделать это, по-видимому, является использование package.skeleton для создания базовых файлов пакета, а затем программная перезапись файла DESCRIPTION и файлов Rd. Проблема заключается в том, что вы теряете автоматически сгенерированные поля, которые гарантируют, что вы запомнили все правильные параметры.

Я хотел бы знать, как вы собираетесь создавать пакеты и писать документы. Существуют ли какие-либо инструменты для облегчения процесса? (roxygen похоже, что он был разработан для такого рода вещей, есть ли у него хороший учебник и есть ли альтернативы?)

Ответы

Ответ 1

Я использую roxygen для всех моих проектов. Например, просмотрите источник пакет webvis. Хэдли также использует roxygen для своей документации (например, см. Его пакет lubridate).

Насколько мне известно, roxygen не задокументирован далеко за пределами вигетты (посмотрите домашняя страница roxygen).

Roxygen хорош, потому что он ведет к грамотному программированию в том смысле, что ваша документация и код бок о бок. Это также упрощает процесс документирования, так как вы работаете со всем сразу. Я определенно рекомендую его и не буду разрабатывать какие-либо пакеты без него на данный момент.

Это не автоматизирует документацию в том смысле, что некоторые инструменты для создания документации (например, javadoc): roxygen интерпретирует R-комментарии, которые должным образом отформатированы, но никак не интерпретирует R-код.

Что касается создания пакета в целом: package-skeleton отлично подходит для начинающих. После того, как вы создали несколько пакетов, в будущем вам может быть проще просто создать все каталоги, NAMESPACE и т.д. Вручную. Особенно, если вы собираетесь следовать некоторым другим практикам, таким как включение демонстрационного каталога, использование roxygen, написание виньетки или включение исходного кода на другие языки.

Наконец, я управляю своими пакетами в Eclipse (StatET); многие из IDE имеют "проектные" представления, которые помогают управлять структурой пакета, поэтому вы также можете использовать более продвинутый редактор.

Ответ 2

Что касается ресурсов с помощью roxygen, с тех пор появилось еще несколько, появилось еще несколько, чтобы процитировать мои собственные заметки:

Часто, когда я google Roxygen или Roxygen2, мне трудно найти документация. Вот компиляция некоторых ключевых ресурсов: