Как Вы пишете свою документацию пакета? [закрытый]
Я не вполне выяснил разумный рабочий процесс для создания пакетов и записи их документации.
Я хочу, чтобы как можно больше процесса (и документация) было автоматически сгенерировано.
Очевидный способ сделать это, кажется, для использования package.skeleton для создания основных файлов пакета затем программно перезапишите DESCRIPTION файл и Rd файлы. Проблема с этим состоит в том, что Вы затем теряете автоматически сгенерированные поля, которые гарантируют, что Вы не забыли документировать все правильные параметры.
Я хотел бы знать, как Вы идете о создании пакетов и записи документации. Действительно ли там какие-либо инструменты доступны для создания процесса легче? (roxygen похож на него, был разработан для этого вида вещи; существует ли хорошее учебное руководство для него? и есть ли какие-либо альтернативы?)
1 ответ
Я использую roxygen для всех своих проектов. Например, просмотрите исходный код для пакета webvis . Хэдли также использует roxygen для своей документации (например, см. Его пакет lubridate ).
Насколько мне известно, roxygen не задокументирован далеко за пределами vigette (посмотрите домашнюю страницу roxygen ).
Roxygen хорош тем, что ведет к грамотному программированию в том смысле, что ваша документация и код находятся рядом. Это также упрощает процесс документирования, поскольку вы работаете со всем сразу. Я определенно рекомендую это, и на данный момент не буду разрабатывать какие-либо пакеты без него.
Тем не менее, он не автоматизирует документацию в том смысле, в каком это делают некоторые инструменты для создания документации (например, javadoc): roxygen интерпретирует правильно отформатированные комментарии R, но никак не интерпретирует код R.
Что касается создания пакета в целом: скелет пакета отлично подходит для начинающих. После того, как вы создали несколько пакетов, вам может быть проще в будущем просто создать все каталоги, NAMESPACE и т. Д. Вручную. Особенно, если вы собираетесь следовать некоторым другим практикам, таким как включение демонстрационного каталога, использование roxygen, написание виньетки или включение исходного кода на других языках.
Наконец, я управляю своими пакетами в Eclipse (StatET); многие из IDE имеют представления «проекта», которые помогают управлять структурой пакета, поэтому вы также можете использовать более продвинутый редактор.