Skip to content

Commit

Permalink
Update Chapter 19: Website (#72)
Browse files Browse the repository at this point in the history 
* Update Chapter 19: Website

* Link all the things!
  • Loading branch information
@jonthegeek
jonthegeek authored Apr 30, 2024
1 parent fe414df commit 0643a14
Show file tree
Hide file tree
Showing 2 changed files with 118 additions and 135 deletions.
253 changes: 118 additions & 135 deletions 19-website.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")`

Expand All @@ -177,7 +160,7 @@
</details>


### Cohort 4
### Cohort 4 {-}

`r knitr::include_url("https://www.youtube.com/embed/9Xux7LQXPWg")`

Expand Down
Binary file added images/19-website/jon_discovers_pkgdown.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 0643a14

Please sign in to comment.