5 More documentation

5.1 readme.md for GitHub

Your GitHub repo needs a readme file to explain to users how to install the package and get started.

You can create readme.Rmd with

usethis::use_readme_rmd()

This will create a draft for you to fill in and knit, and set git hooks to remind you to commit both the readme.Rmd and the resulting readme.md together. Do not edit the readme.md by hand. If you don’t want any R code in the readme, you can use usethis::use_readme_md() instead.

5.2 Vignettes

A vignette is a long-form documentation for your package. It can be anything from a walk-through of how to use the package to a detailed explanation of the implementation.

Create a vignette with:

usethis::use_vignette("my-vignette")

which will modify the DESCRIPTION file, and draft the R markdown file vignettes/my-vignette.Rmd. Fill it in and knit it.

5.3 A package website

packagedown is an amazing package that takes your packages help files and vignettes and makes them into a website that you can host on GitHub.

For a minimal website, you need and run

# Run *once* to configure package to use pkgdown
usethis::use_pkgdown()
# Run to build the website
pkgdown::build_site()

Commit and push the built webpages, the configure your GitHub repo to support publishing (about 5 clicks).

You can even set up GitHub actions to build the website automatically after every push.

# More documentation

## readme.md for GitHub 

Your GitHub repo needs a readme file to explain to users how to install the package and get started.

You can create `readme.Rmd` with 

```{r use-readme-rmd}
usethis::use_readme_rmd()
```

This will create a draft for you to fill in and knit, and set git hooks to remind you to commit both the `readme.Rmd` and the resulting `readme.md` together.
Do not edit the `readme.md` by hand. 
If you don't want any R code in the readme, you can use `usethis::use_readme_md()` instead.

## Vignettes

A vignette is a long-form documentation for your package.
It can be anything from a walk-through of how to use the package to a detailed explanation of the implementation.

Create a vignette with:

```{r vignette}
usethis::use_vignette("my-vignette")
```
 which will modify the DESCRIPTION file, and draft the R markdown file `vignettes/my-vignette.Rmd`.
 Fill it in and knit it.

## A package website

[`packagedown`](https://pkgdown.r-lib.org/articles/pkgdown.html) is an amazing package that takes your packages help files and vignettes and makes them into a website that you can host on GitHub.

For a minimal website, you need and run

```{r packagedown}
# Run *once* to configure package to use pkgdown
usethis::use_pkgdown()
# Run to build the website
pkgdown::build_site()
```

Commit and push the built webpages, the [configure your GitHub repo](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) to support publishing (about 5 clicks).

You can even set up GitHub actions to build the website automatically after every push.