12 Including extras for litr

12.1 README with hex sticker

We include a README.Rmd and then generate the README.md based on it:

add_readme(file.path("..", "source-files", "README.Rmd"))
## ✔ Writing 'README.Rmd'
## ✔ Adding '^README\\.Rmd$' to '.Rbuildignore'
## ✔ Creating '.git/hooks/'
## ✔ Writing '.git/hooks/pre-commit'

Let’s add the litr hex sticker too (which is referred to in the README).

add_hex_sticker(file.path("..", "source-files", "litr-hex.png"))

Let’s also add a figure we include in the README.

fs::file_copy(file.path("..", "source-files", "diagram3.png"),
              file.path("man", "figures"))

12.2 Vignettes

add_vignettes(c(file.path("..", "source-files", "package-templates.Rmd"),
                file.path("..", "source-files", "packages-in-the-wild.Rmd"),
                file.path("..", "source-files", "faqs.Rmd"),
                file.path("..", "source-files", "basic-example.Rmd"),
                file.path("..", "source-files", "videos.Rmd")))

The templates vignette uses dplyr and stringr, so we add them as “Suggests” in the DESCRIPTION file:

usethis::use_package("dplyr", type = "Suggests")
## ✔ Adding 'dplyr' to Suggests field in DESCRIPTION
## • Use `requireNamespace("dplyr", quietly = TRUE)` to test if package is installed
## • Then directly refer to functions with `dplyr::fun()`
usethis::use_package("stringr", type = "Suggests")
## Warning: Package 'stringr' is already listed in 'Imports' in DESCRIPTION, no
## change made.

12.3 A pkgdown site

We’ll first add the github url to the DESCRIPTION file.

desc::desc_set("URL", "https://github.com/jacobbien/litr-project/tree/main/litr")
## Package: litr
## Title: Literate Programming for Writing R Packages
## Version: 0.9.2
## Authors@R (parsed):
##     * Jacob Bien <jbien@usc.edu> [aut, cre]
##     * Patrick Vossler [aut]
## Description: Allows one to fully create an R package in a single .Rmd
##     file.  Includes functionality and .Rmd templates for a literate
##     programming approach to R package development.
## License: MIT + file LICENSE
## URL: https://github.com/jacobbien/litr-project/tree/main/litr
## Imports:
##     bookdown,
##     desc,
##     devtools,
##     digest,
##     fansi,
##     fs,
##     knitr,
##     pkgdown,
##     rmarkdown,
##     stringr,
##     usethis,
##     xfun,
##     xml2,
##     yaml
## Suggests:
##     dplyr,
##     Rcpp,
##     testthat (>= 3.0.0)
## VignetteBuilder:
##     knitr
## Config/testthat/edition: 3
## Encoding: UTF-8
## Roxygen: list(markdown = TRUE)
## RoxygenNote: 7.3.1

Next, we create the pkgdown site. The customizations come from the source file source-files/_pkgdown.yml.

pkgdown_yml <- file.path("..", "source-files", "_pkgdown.yml")
add_pkgdown(pkgdown_yml)
## ✔ Adding '^_pkgdown\\.yml$', '^docs$', '^pkgdown$' to '.Rbuildignore'
## ── Installing package litr into temporary library ──────────────────────────────
## ── Building pkgdown site for package litr ──────────────────────────────────────
## Reading from: /Users/jacobbien/Documents/GitHub/litr-project/litr
## Writing to: /Users/jacobbien/Documents/GitHub/litr-project/docs
## ── Initialising site ───────────────────────────────────────────────────────────
## ── Building favicons ───────────────────────────────────────────────────────────
## ℹ Building favicons with <https://realfavicongenerator.net> ...
## Copying pkgdown/favicon/apple-touch-icon-120x120.png,
## pkgdown/favicon/apple-touch-icon-152x152.png,
## pkgdown/favicon/apple-touch-icon-180x180.png,
## pkgdown/favicon/apple-touch-icon-60x60.png,
## pkgdown/favicon/apple-touch-icon-76x76.png,
## pkgdown/favicon/apple-touch-icon.png, pkgdown/favicon/favicon-16x16.png, and
## pkgdown/favicon/favicon-32x32.png
## to apple-touch-icon-120x120.png, apple-touch-icon-152x152.png,
## apple-touch-icon-180x180.png, apple-touch-icon-60x60.png,
## apple-touch-icon-76x76.png, apple-touch-icon.png, favicon-16x16.png, and
## favicon-32x32.png
## ── Building home ───────────────────────────────────────────────────────────────
## Reading LICENSE.md
## Writing `404.html`
## ── Building function reference ─────────────────────────────────────────────────
## Reading man/add_chunk_label_hyperlinks.Rd
## Reading man/add_function_hyperlinks.Rd
## Reading man/add_hex_sticker.Rd
## Reading man/add_pkgdown.Rd
## Reading man/add_readme.Rd
## Reading man/add_text_to_file.Rd
## Reading man/add_vignettes.Rd
## Reading man/check_unedited.Rd
## Reading man/create_from_template.Rd
## Reading man/description_litr_hash_field_name.Rd
## Reading man/description_litr_version_field_name.Rd
## Reading man/do_not_edit_message.Rd
## Reading man/document.Rd
## Reading man/draft.Rd
## Reading man/draft_armadillo.Rd
## Reading man/draft_bookdown.Rd
## Reading man/draft_data.Rd
## Reading man/draft_extras.Rd
## Reading man/draft_rcpp.Rd
## Reading man/find_labels.Rd
## Reading man/get_package_directory.Rd
## Reading man/get_params_used.Rd
## Reading man/hash_package_directory.Rd
## Reading man/insert_hrefs.Rd
## Reading man/litr-package.Rd
## Reading man/litr_gitbook.Rd
## Reading man/litr_html_document.Rd
## Reading man/litr_pdf_document.Rd
## Reading man/litrify_output_format.Rd
## Reading man/load_all.Rd
## Reading man/make_noticeable.Rd
## Reading man/read_hash_from_description.Rd
## Reading man/remove_rstudio_extras.Rd
## Reading man/render.Rd
## Reading man/replace_ansi_sequences.Rd
## Reading man/restore_knitr_objects.Rd
## Reading man/send_to_package.Rd
## Reading man/setup.Rd
## Reading man/test_litr.Rd
## Reading man/with_cleanup.Rd
## Reading man/write_hash_to_description.Rd
## Reading man/write_version_to_description.Rd
## ── Building articles ───────────────────────────────────────────────────────────
## Reading vignettes/basic-example.Rmd
## Reading vignettes/faqs.Rmd
## Reading vignettes/package-templates.Rmd
## Reading vignettes/packages-in-the-wild.Rmd
## Reading vignettes/videos.Rmd
## Writing sitemap.xml
## ── Building search index ───────────────────────────────────────────────────────
## ── Finished building pkgdown site for package litr ─────────────────────────────
## ── Finished building pkgdown site for package litr ─────────────────────────────

We follow this pkgdown vignette in our customizations. Here is the contents of the _pkgdown.yml that was used:

cat(readLines("../source-files/_pkgdown.yml"), sep = '\n')
destination: ../docs/

url: ~
template:
  bootstrap: 5
  bootswatch: cosmo

repo:
  url:
    home: https://github.com/jacobbien/litr-project/tree/main/litr/   
    source: https://github.com/jacobbien/litr-project/tree/main/litr/
    issue: https://github.com/jacobbien/litr-project/issues/
    user: https://github.com/

authors:
  Jacob Bien:
    href: http://faculty.marshall.usc.edu/jacob-bien/
  Patrick Vossler:
    href: https://www.patvoss.me/

navbar:
  structure:
    left:  [reference, articles]
    right: [github]
  components:
    github:
      icon: fa-github
      href: https://github.com/jacobbien/litr-project/tree/main/litr/

reference:
- title: Primary functions
  desc: >
    These are the functions you'll use the most.
  contents:
    - draft
    - render
    - document
    - load_all

- title: Working from template
  desc: >
    These are functions for quickly creating different kinds of R packages.
  contents:
    - draft
    - draft_bookdown
    - draft_data
    - draft_rcpp
    - draft_extras
    - draft_armadillo

- title: Functions for adding "extras" to your package
  desc: >
    These functions can help you add a README, vignettes, a pkgdown site, and a hex sticker to your package.
  contents:
    - add_readme
    - add_vignettes
    - add_pkgdown
    - add_hex_sticker

- title: Custom output formats
  desc: >
    These are the functions for producing different output formats.
  contents:
    - litr_html_document
    - litr_pdf_document
    - litr_gitbook
    - litrify_output_format

After this step, you can locally see the site by opening docs/index.html in the browser. You can then copy the docs directory to your website’s server and you’re done.