Презентация к 9 уроку курса разработка пакетов на языке R

1. Разработка свободной
Документации пакета
Виньетки, Readme, News
Алексей Селезнёв

2. Мой telegram канал

3. ВИНЬЕТКА – СВОБОДНЫЙ ТИП
ДОКУМЕНТАЦИИ, В КОТОРОМ ВЫ
ПОДРОБНО РАССКАЗАНО КАК
КОМПЛЕКСНО ИСПОЛЬЗОВАТЬ
ВАШ ПАКЕТ

4. Рабочий процесс
1. Используйте функцию usethis::use_vignette("my-vignette"), которая сделает следующее:
1. Создаст каталог vignettes/
2. Редактирует файл DESCRIPTION, в поле Suggests добавляя пакеты Knitr и Rmarkdown
3. Генерирует виньетку vignettes/my-vignette.Rmd.
4. Добавляет некоторые шаблоны в файл .gitignore гарантирующие, что файлы, созданные в
результате предварительного просмотра ваших виньеток, останутся вне системы контроля версий.
2. Наполните вашу виньетку контентом.
3. Периодически рендите вашу виньетку с помощью devtools::build_rmd("vignettes/my-
vignette.Rmd"), и смотрите, что получается. Другие способы рендинга будут
использовать не разрабатываемую версию вашего пакета, а ту которая была уже
установлена в основную библиотеку.
4. Повторяйте все шаги пока не получите нужный вам результат.

5. Метаданные виньетки
• title - это заголовок, который появляется в виньетке. При редактировании этого поля,
обязательно внесите такие же изменения в VignetteIndexEntry{}. Они должны быть
одинаковыми, но, к сожалению, это не происходит автоматически.
• output - формат вывода. Существует множество вариантов, но rmarkdown::html_vignette
разработан специально для создания виньеток.
• vignette - блок специальных метаданных, необходимых R. Единственная запись, которую
вам, возможно, придется изменить, — это файл VignetteIndexEntry{}.
• author – автор виньетки.
• date – дата обновления виньетки.

6. Rmd разметка
• # Header1 – Заголовки
• *italic* - Курсив
• **bold** - Жирный шрифт
• `1 + 1` - Моноширинный шрифт
• `r 1 + 1` - Исполняемый inline код
• [r02pro](https://r02pro.github.io/) – Ссылка
• ^[] - Сноска

7. Rmd разметка
• Списки:

8. Rmd разметка
Графики добавляются с помощью блока кода

9. Rmd разметка
• Таблицы создаются с помощью функции kable():
• Либо других пакетов генерирующих из дата фреймов таблицы в html формате, например
htmlTable, kableExtra, DT, gt

10. Опции чанков
• label – Название чанка
• eval – Следует ли выполнять код чанка
• echo - Следует ли отображать исходный код в выходном документе
• results – Управляет отображением результатов выполнения кода: markup, asis, hold, hide
• warning, error, message – Надо ли выводить в результате выполнения кода
предупреждения, ошибки или сообщения

11. R CMD BUILD
• Исходные файлы виньеток, которые вы создаёте в папке vignetts/ присутствуют только на
стадии разработки не входят в сборку пакета.
• При сборке пакета все виньетки в виде html файлов помещаются в inst/doc/.
• При установке пакета, в его конечном состоянии каталог doc/ помещается на верхний
уровень, т.е. в корень папки пакета.

12. README – Файл направленный на
новых пользователей вашего
пакета. Он так же будет главной
страницей сайта пакета, и
репозитория пакета на GitHub.

13. README
Файл README должен отвечать на следующие вопросы:
• Какую проблему решает ваш пакет
• Как использовать его функционал
Обычно README состоит из следующих пунктов:
• Параграф, описывающий общее назначение пакета.
• Пример, показывающий, как использовать пакет для решения простой проблемы.
• Инструкции по установке с кодом, который можно скопировать и вставить в R.
• Обзор, описывающий основные компоненты пакета. Для более сложных пакетов это будет
указывать на виньетки для более подробной информации. Это также хорошее место, чтобы
описать, как ваш пакет вписывается в экосистему целевого домена.

14. README
• Для создания README файла используйте функцию usethis::use_readme_rmd().
• Используйте devtools::build_readme() для рендинга и просмотра вашего README.

15. README
Набор функций для добавления различных бейджей:
• usethis::use_cran_badge() - сообщает текущую версию вашего пакета в CRAN.
• usethis::use_coverage() - сообщает о тестовом покрытии.
• use_github_actions() - сообщают о R CMD check о состоянии вашего пакета разработки.

16. NEWS – Файл направленный на
пользователей, которые уже
используют ваш пакет. Данный
файл содержит описание всех
изменений в пакете.

17. NEWS
Рабочий процесс:
• Наиболее удобным способом его создания является функция usethis::use_news_md().
• Перед выпуском новой версии пакета используйте функцию usethis::use_version().
Оформление NEWS:
• Каждое изменение должно быть частью маркированного списка.
• Если у вас много изменений, возможно, вы захотите разбить их с помощью подзаголовков,
## Major changes, ## Bug fixesи т. д.

18. СПАСИБО ЗА ВНИМАНИЕ