diff --git a/19-website.Rmd b/19-website.Rmd index def87c4..6c33d58 100644 --- a/19-website.Rmd +++ b/19-website.Rmd @@ -2,166 +2,149 @@ **Learning objectives:** -- Why a website benefits your package -- Some handy `usethis::` and `pkgdown::` functions to automatically generate the website -- A workflow to publish to the internet using Git, GitHub Actions & GitHub Pages -- Optional extras to customise your pkgdown site - -## A website to call home - -- Our package has many different documents: - - Function documentation (or help topics) - - Documentation of data sets - - Vignettes (and/or articles) - - `README` and `NEWS` - -- We can bring together all of our documentation into an easy to navigate website -- The pkgdown package contains some easy to use functions to create a website automagically if your package has a valid structure - -## `usethis::use_pkgdown` - Initiate a site - -- `usethis::use_pkgdown()` is run once and will create a minimal setup where we can then start to use pkgdown -- This will: - - Create a `_pkgdown.yml` file (the main config file for pkgdown) - - Adds things to `.Rbuildignore` (stops pkgdown things being included in your package bundle) - - Adds `docs/` to `.gitignore`. This co-opts you into building and deploying your website elsewhere (GitHub Actions & Pages). `docs/` would just be used to render as a local preview - -## `pkgdown::build_site()` - render your site -- You will repeatedly use `pkgdown::build_site()` to render your website locally -- This should render and open your website in your default browser -- You can look in the `docs/` directory to see the files that make up your package -- Congrats! You now have a barebones, locally rendered website... but how to deploy to the internet? - -## Deployment - -- The easiest way to show your website on the internet is to: - - Use Git & host the package on GitHub - - Use GitHub Actions to run `pkgdown::build_site()` every time you push a change to GitHub - - Use GitHub Pages to serve your static website - -## `usethis::use_pkgdown_github_pages()` - -- `usethis::use_pkgdown_github_pages()` is called once and will run through several steps: - - Initialises an empty orphan branch in your GitHub repo (`gh-pages`) - - This branch only exists on GitHub and only tracks the files that make up the website (i.e. what we see in `docs/`) - - Turns on GitHub Pages for your repo and points it to the `gh-pages` branch - - Copies the config file for a GHA workflow (shows up in `.github/workflows/pkgdown.yaml`) - - Adds the URL for your site as the homepage for your GitHub repo - - Adds the URL for your site to `DESCRIPTION` and `_pkgdown.yml` - -- It may take a couple of minutes, but you should now be able to visit the website URL (you will see it listed in the console output). - - the default URL is in this form: - `https://USERNAME.github.io/REPONAME/` -- You have a website! Sweet as! - -## C'est fini? - -- You could stop here if you wanted, you have a basic website that is helpful to users -- Or you could make it look even more sweet by customising stuff (`vignette("pkgdown", package = "pkgdown")` is a good place to start) - -## Hex logos - -- The six sided logos and stickers that everyone loves -- Design specs and sticker printing businesses can be found [here](http://hexb.in/sticker.html) -- There's an [R package](https://github.com/GuangchuangYu/hexSticker) for that -- When you have your logo, `usethis::use_logo()` will scale and add your logo to your `man/figures/` folder. pkgdown will also discover this and add to your site - -## Functions Reference Index - -- the `reference/` contains a page for each function that has a `.Rd` help topic in `man/` -- pkgdown will execute and render all of your examples - - This is a good opportunity to make sure they look the way they are supposed to -- The help topics will be linked to locations within/outside of your site - - hark back to chapter 17 and recall enclosing functions in `[]` when mentioned in roxygen comments - - pkgdown will automatically hyperlink to the relevant pages for your function. - - Inbound links from other people's packages require extra work: - - Published to CRAN - - the `URL` field in the `DESCRIPTION` file must be populated with the URL of your pkgdown site and GitHub repo - - your `_pkgdown.yml` file must include the URL for your site. - - devtools generally does this configuration for you - -## Functions Index Organisation - -- The reference index is an alphabetically ordered list of functions -- You might like to curate this if you have lots of functions [(e.g. dplyr)](https://dplyr.tidyverse.org/reference/) -- This can be done by providing a `reference` field in `_pkgdown.yml` e.g. for dplyr: - - ``` +- Create a package website with {pkgdown}. +- Deploy a package website with GitHub Actions. +- Customize your package website. + +## This is super easy! {-} + +> We hear that some folks put off “learning pkgdown”, because they think it’s going to be a lot of work. But then they eventually execute the two commands we show next and have a decent website in less than five minutes! + +[![A tweet from Jon Harmon: I put of creating a pkgdown site for my various #RStats projects because I thought I didn't have time to learn how. Then Monday I typed usethis::use_pkgdown_github_pages() and voila this exists: r4ds.github.io/cookies Sometimes just try the thing!](images/19-website/jon_discovers_pkgdown.png)](https://cookies.shinyworks.org/) + +(now at [cookies.shinyworks.org](https://cookies.shinyworks.org/)) + +## We're so close already! {-} + +We already have: + +- Function help +- Dataset documentation +- Vignettes/articles +- `README` and `NEWS` + +[{pkgdown}](https://pkgdown.r-lib.org/index.html) wraps all of that into a website + +## It's so easy! {-} + +- [`usethis::use_pkgdown()`](https://usethis.r-lib.org/reference/use_pkgdown.html): + - Creates `_pkgdown.yml` ([{pkgdown}](https://pkgdown.r-lib.org/index.html) config) + - Adds [{pkgdown}](https://pkgdown.r-lib.org/index.html) things to `.Rbuildignore` + - Adds `docs/` (local render) to `.gitignore` + - We'll use GitHub Actions to build the real site +- [`pkgdown::build_site()`](https://pkgdown.r-lib.org/reference/build_site.html): render locally & open in browser + +## It's even easier! {-} + +[`usethis::use_pkgdown_github_pages()`](https://usethis.r-lib.org/reference/use_pkgdown.html): + +- (runs [`usethis::use_pkgdown()`](https://usethis.r-lib.org/reference/use_pkgdown.html)) +- Initializes `gh-pages` in pkg GitHub +- Turns on GitHub Pages & points to `gh-pages` branch + - Free for public repos! +- Copies GHA workflow config to `.github/workflows/pkgdown.yaml` +- Adds URL as homepage for GitHub repo +- Adds URL to `DESCRIPTION` & `_pkgdown.yml` + +## Is that it? {-} + +- You can be done if you want! +- Lots more customization options! +- [`vignette("pkgdown", package = "pkgdown")`](https://pkgdown.r-lib.org/articles/pkgdown.html) = good place to start + +## Hex logos {-} + +- #RStats 💗 hexagons! +- Design specs and sticker printing businesses @ [hexb.in/sticker.html](http://hexb.in/sticker.html) +- [{hexSticker}](https://github.com/GuangchuangYu/hexSticker) 📦 for that +- [`usethis::use_logo()`](https://usethis.r-lib.org/reference/use_logo.html) to scale & add logo to site + +## Functions reference {-} + +- `reference/` = list of all function help pages +- [{pkgdown}](https://pkgdown.r-lib.org/index.html) automatically lists all exported docs +- `[function()]` and `[pkg::function()]` auto-link + - Be sure to use steps above to set up properly + +## Functions reference organisation {-} + +- `reference/` alphabetical by default +- Can curate with `reference` field in `_pkgdown.yml` +- Example: [{dplyr}](https://dplyr.tidyverse.org/reference/) + - (we'll see how on next slide) + +## Functions reference example {-} + +``` reference: - title: Data Frame Verbs - + - subtitle: Rows - desc: > - Verbs that principally operate on rows. - contents: - - arrange - - distinct + desc: > + Verbs that principally operate on rows. + contents: + - arrange + - distinct ... - subtitle: Columns - desc: > - Verbs that principally operate on columns. - contents: - - glimpse - - mutate + desc: > + Verbs that principally operate on columns. + contents: + - glimpse + - mutate ... - ``` - -## Vignettes and articles +``` -- A packages vignettes will appear (rendered) in the _Articles_ drop down menu -- Vignettes can also be linked to automatically (recall using `vignette("some-topic")` inline from Chapter 17) -- pkgdown will detect that format and automatically link to it on your website. Use this format in your roxygen comments: - - for your own vignette `vignette("some-topic")` - - for an external package vignette `vignette("some-topic", package = "somepackage")` - - this will not work for non-vignette articles (use a normal URL for these e.g. `[]()`) - - make sure to use backticks and parentheses when you refer to a function in vignettes e.g.: - ``` - `thisfunction()` or `otherpkg::otherfunction()` - ``` - -## Vignettes and articles Index organisation +## Vignettes & articles {-} -- The default is to have your vignettes/articles appear alphabetically -- You can customise this -- `?pkgdown::build_articles` has more info on this +- Vignettes in *Articles* drop-down +- Link between vignettes with `vignette("some-topic")` or `vignette("some-topic", package = "somepackage")` + - Reference functions with backticks and () + +``` +`thisfunction()` or `otherpkg::otherfunction()` +``` -## Non-vignette articles +## Vignettes & articles organisation {-} -- Non-vignette articles are not shipped with the package bundle -- The main reason to have a non-vignette article is to avoid executing gnarly code -- This might be due to: - - The code requiring authentication (e.g. googledrive package) - - You use a package but don't want to formally depend on it - - Content with lots of figures that causes size issues (e.g. larger than CRAN's size constraints) +- *Articles* alphabetical by default +- [`?pkgdown::build_articles`](https://pkgdown.r-lib.org/reference/build_articles.html) to customize -## Development Mode +## Non-vignette articles {-} -> The development field allows you to generate different sites for the development and released versions of your package. ~ [pkgdown](https://pkgdown.r-lib.org/reference/build_site.html#development-mode) +- Articles = vignette-like things but not shipped with 📦 +- Allow you to avoid executing gnarly code + - Code requiring authentication (e.g. [{googledrive}](https://googledrive.tidyverse.org/articles/index.html)) + - Use 📦 but don't want to formally depend on it + - Lots of figures/videos > CRAN's size constraints -- In the `_pkgdown.yml` file there is a `mode:` field. This can be set to `release`, `development`, `auto` and more. -- `release` is default and site gets written to `docs/` (just use this if you have a small user base). This will generate a single site, but a user downloading from CRAN may get documentation from your in development documents (e.g. functions that may not exist in the CRAN package yet) -- `devel` site is writen to `docs/dev/` and gets a danger class, and a tool tip warning these documents are in development. A `noindex` tag stops search engines indexing this site. You would have two sites the CRAN release in `docs/` and the development release in `docs/dev/` +## Development Mode {-} - - Example of this: - - readr.tidyverse.org documents the released version, i.e. what install.packages("readr") delivers. - - readr.tidyverse.org/dev/ documents the dev version, i.e. what install_github("tidyverse/readr") delivers. +Different site for release vs development! -- `auto` will automatically determine the mode based on the version number (use if your package has a broad user base) +- `_pkgdown.yml` `mode:` field = `release`, `development`, `auto` (& `unreleased`) +- `release` (default) = single site w/ everything + - Fine for most packages + - [readr.tidyverse.org = release (CRAN)](https://readr.tidyverse.org) +- `devel` = separate site in `docs/dev` + - [readr.tidyverse.org/dev = devel (`pak::pak("tidyverse/readr")`)](https://readr.tidyverse.org/dev) +- `auto` = automatically switch based on vnum +- FYI `unreleased` basically puts `devel` in `docs` -## Meeting Videos +## Meeting Videos {-} -### Cohort 1 +### Cohort 1 {-} `r knitr::include_url("https://www.youtube.com/embed/isKbovi62k4")` -### Cohort 2 +### Cohort 2 {-} `r knitr::include_url("https://www.youtube.com/embed/5VAvPvL18I0")` -### Cohort 3 +### Cohort 3 {-} `r knitr::include_url("https://www.youtube.com/embed/LkSKXeZTD-0")` @@ -177,7 +160,7 @@ -### Cohort 4 +### Cohort 4 {-} `r knitr::include_url("https://www.youtube.com/embed/9Xux7LQXPWg")` diff --git a/images/19-website/jon_discovers_pkgdown.png b/images/19-website/jon_discovers_pkgdown.png new file mode 100644 index 0000000..1b04aeb Binary files /dev/null and b/images/19-website/jon_discovers_pkgdown.png differ