From c2a6389e01bea3dcece42c798a76d77b8b4049fc Mon Sep 17 00:00:00 2001 From: olivroy Date: Wed, 5 Jun 2024 10:28:23 -0400 Subject: [PATCH] Recommend `usethis::use_pkgdown_github_pages()` everywhere. --- R/init.R | 2 +- README.Rmd | 12 +++++------- README.md | 22 +++++++++------------- man/init_site.Rd | 2 +- vignettes/pkgdown.Rmd | 27 ++++++++++++++------------- 5 files changed, 30 insertions(+), 35 deletions(-) diff --git a/R/init.R b/R/init.R index fa0e2d50c..90ddc21d3 100644 --- a/R/init.R +++ b/R/init.R @@ -12,7 +12,7 @@ #' display of your site. #' #' # Build-ignored files -#' We recommend using [usethis::use_pkgdown()] to build-ignore `docs/` and +#' We recommend using [usethis::use_pkgdown_github_pages()] to build-ignore `docs/` and #' `_pkgdown.yml`. If use another directory, or create the site manually, #' you'll need to add them to `.Rbuildignore` yourself. A `NOTE` about #' an unexpected file during `R CMD CHECK` is an indication you have not diff --git a/README.Rmd b/README.Rmd index 3218946ea..157fe0d4f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -44,17 +44,15 @@ pak::pak("r-lib/pkgdown") Get started with [usethis](https://usethis.r-lib.org/): ```{r, eval = FALSE} -# Run once to configure your package to use pkgdown -usethis::use_pkgdown() +# Run once to configure your package to use and deploy pkgdown +usethis::use_pkgdown_github_pages() ``` -Then use pkgdown to build your website: -```{r, eval = FALSE} -pkgdown::build_site() -``` +This adds the necessary components and sets up GitHub Actions for automatic site building when deploying. +Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`. [^1] -This generates a `docs/` directory containing a website. Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`. Read `vignette("pkgdown")` for more details, and to learn how to deploy your site to GitHub pages. +[^1]: If you don't use GitHub, you can use `usethis::use_pkgdown()` + `pkgdown::build_site()` to create a website. ### pkgdown 2.0.0 and Bootstrap 5 diff --git a/README.md b/README.md index 6db2d7cca..453954bc0 100644 --- a/README.md +++ b/README.md @@ -48,21 +48,14 @@ pak::pak("r-lib/pkgdown") Get started with [usethis](https://usethis.r-lib.org/): ``` r -# Run once to configure your package to use pkgdown -usethis::use_pkgdown() +# Run once to configure your package to use and deploy pkgdown +usethis::use_pkgdown_github_pages() ``` -Then use pkgdown to build your website: - -``` r -pkgdown::build_site() -``` - -This generates a `docs/` directory containing a website. Your -`README.md` becomes the homepage, documentation in `man/` generates a -function reference, and vignettes will be rendered into `articles/`. -Read `vignette("pkgdown")` for more details, and to learn how to deploy -your site to GitHub pages. +This adds the necessary components and sets up GitHub Actions for +automatic site building when deploying. Your `README.md` becomes the +homepage, documentation in `man/` generates a function reference, and +vignettes will be rendered into `articles/`. [^1] ### pkgdown 2.0.0 and Bootstrap 5 @@ -114,3 +107,6 @@ new pkgdown techniques. Please note that this project is released with a [Contributor Code of Conduct](https://pkgdown.r-lib.org/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms. + +[^1]: If you don’t use GitHub, you can use `usethis::use_pkgdown()` + + `pkgdown::build_site()` to create a website. diff --git a/man/init_site.Rd b/man/init_site.Rd index 7d638ddf6..5e0638c91 100644 --- a/man/init_site.Rd +++ b/man/init_site.Rd @@ -22,7 +22,7 @@ See \code{vignette("customise")} for the various ways you can customise the display of your site. } \section{Build-ignored files}{ -We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}} to build-ignore \verb{docs/} and +We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown_github_pages()}} to build-ignore \verb{docs/} and \verb{_pkgdown.yml}. If use another directory, or create the site manually, you'll need to add them to \code{.Rbuildignore} yourself. A \code{NOTE} about an unexpected file during \verb{R CMD CHECK} is an indication you have not diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index ea2291b7e..643dda46f 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -10,21 +10,24 @@ vignette: > --- The goal of pkgdown is to make it easy to make an elegant and useful package website with a minimum of work. -You can get a basic website up and running in just a couple of minutes: +You can get a basic website up and running in just a couple of minutes. If you're using GitHub, we recommend setting up pkgdown and GitHub actions to automatically build and publish your site: ```{r, eval = FALSE} -# Run once to configure package to use pkgdown -usethis::use_pkgdown() -# Run to build the website -pkgdown::build_site() +# Run this once to publish your site regularly +usethis::use_pkgdown_github_pages() ``` -If you're using GitHub, we also recommend setting up GitHub actions to automatically build and publish your site: +If you are not using GitHub, you will have to run `pkgdown::build_site()` manually everytime you want to update the site. ```{r, eval = FALSE} -usethis::use_pkgdown_github_pages() +# Run once +# Remove docs/ from gitignore to ensure it is checked into git. +usethis::use_pkgdown() +# Run everytime you want to update your site +pkgdown::build_site() ``` + While you'll get a decent website without any additional work, if you want a website that really pops, you'll need to read the rest of this vignette. It starts by showing you how to configure pkgdown with a `_pkgdown.yml`. You'll learn about the main components of the site (the home page, reference, articles, and news), and then how to publish and promote your site. @@ -118,8 +121,7 @@ It is recommended to name your intro article with your package name to generate Due to the way that pkgdown has to integrate R Markdown generated HTML with its own HTML, relatively little control is available over the output format. You can see the details in `?build_articles`. -If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of `vignettes/` (e.g. `vignettes/web_only`) or add it to `.Rbuildignore` (and make sure that there's no `vignettes:` section in the yaml header). See `usethis::use_article()` for an automated way to do this. -In the extreme case where you want to produce only articles but not vignettes, you should add the complete `vignettes/` directory to `.Rbuildignore` and ensure that DESCRIPTION does not have a `VignetteBuilder` field. +If you want to include an [article](https://r-pkgs.org/website.html#non-vignette-articles) on the website but not in the package (e.g., because it's large), you can use `usethis::use_article()` to set it up. ## News @@ -147,10 +149,9 @@ See `?build_news` for more customisation options including how to: ## Publishing -If you use GitHub, there are two ways to publish your site on GitHub Pages: - -- Use GitHub actions to automatically build and publish the site every time you make a change. - The easiest way to set this up is to run `usethis::use_pkgdown_github_pages()`, and if you need to customize the action, see [README.md r-lib/actions](https://github.com/r-lib/actions/tree/v2-branch/examples#build-pkgdown-site). +If you use GitHub, the easiest way to build and publish your site is via GitHub actions. +Using GitHub actions automatically builds and publishes the site every time you make a change. +The easiest way to set this up is to run `usethis::use_pkgdown_github_pages()`, and if you need to customize the action, see [README.md r-lib/actions](https://github.com/r-lib/actions/tree/v2-branch/examples#build-pkgdown-site). ## Promoting