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

Question

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

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

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

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

Answer 1

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

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

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

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

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

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

Answer 2

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

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

• У Хэдли Уикхема отличный введение в основные функции Roxygen 2

• Есть такие несколько виньеток , перечисленных на сайте Cran для Roxygen 2

• В RStudio есть заметки по запуск Roxygen

• исходный код пакета roxygen2 на github