 – Ссылка
• ^[] - Сноска](https://image.slidesharecdn.com/9-vignetts-230911135904-0bfc826c/85/9-vignetts-pdf-6-320.jpg)
9-vignetts.pdf
- 1. Разработка свободной Документации пакета Виньетки, Readme, News Алексей Селезнёв
- 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/) – Ссылка • ^[] - Сноска
- 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и т. д.