From 08404807ae67b632676edc46a0cc8556fc6f9f8a Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:40:35 -0400 Subject: [PATCH 01/17] Remove check_pkgdown duplicate (now documented with pkgdown_sitrep) + correct links (avoid linking to deploy_site_github (superseded)) --- R/build.R | 26 +++++++++++++------------- man/build_site.Rd | 2 +- pkgdown/_pkgdown.yml | 5 ++--- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/R/build.R b/R/build.R index 2c5f5e9cf..a19531be8 100644 --- a/R/build.R +++ b/R/build.R @@ -28,7 +28,7 @@ #' It specifies where the site will be published and is used to allow other #' pkgdown sites to link to your site when needed (`vignette("linking")`), #' generate a `sitemap.xml`, automatically generate a `CNAME` when -#' [deploying to github][deploy_site_github], generate the metadata needed +#' [deploying to github][build_site_github_pages()], generate the metadata needed #' rich social "media cards" (`vignette("metadata")`), and more. #' #' * `title` overrides the default site title, which is the package name. @@ -37,7 +37,7 @@ #' # Navbar and footer #' #' The `navbar` and `footer` fields control the appearance of the navbar -#' footer which appear on every page. Learn more about these fields in +#' footer which appear on every page. Learn more about these fields in #' `vignette("customise")`. #' #' # Search @@ -58,8 +58,8 @@ #' ### Setting development mode #' #' The development `mode` of a site controls where the built site is placed -#' and how it is styled (i.e. the colour of the package version in the -#' navbar, the version tooltip), and whether or not the site is indexed by +#' and how it is styled (i.e. the colour of the package version in the +#' navbar, the version tooltip), and whether or not the site is indexed by #' search engines. There are four possible modes: #' #' * **automatic** (`mode: auto`): determines the mode based on the version: @@ -69,9 +69,9 @@ #' * everything else -> release. #' #' * **release** (`mode: release`), the default. Site is written to `docs/` -#' and styled like a released package, even if the content is for an -#' unreleased or development version. Version in navbar gets the default -#' colouring. Development badges are not shown in the sidebar +#' and styled like a released package, even if the content is for an +#' unreleased or development version. Version in navbar gets the default +#' colouring. Development badges are not shown in the sidebar #' (see `?build_home`). #' #' * **development** (`mode: devel`). Site is written to `docs/dev/`. @@ -85,8 +85,8 @@ #' package is not yet on CRAN. #' Development badges are shown in the sidebar (see `?build_home`). #' -#' Use `mode: auto` if you want both a released and a dev site, and -#' `mode: release` if you just want a single site. It is very rare that you +#' Use `mode: auto` if you want both a released and a dev site, and +#' `mode: release` if you just want a single site. It is very rare that you #' will need either devel or unreleased modes. #' #' You can override the mode specified in the `_pkgdown.yml` by setting @@ -178,12 +178,12 @@ #' #' To capture usage of your site with a web analytics tool, you can make #' use of the `includes` field to add the special HTML they need. This HTML -#' is typically placed `in_header` (actually in the ``), `before_body`, -#' or `after_body`. +#' is typically placed `in_header` (actually in the ``), `before_body`, +#' or `after_body`. #' You can learn more about how includes work in pkgdown at #' . #' -#' I include a few examples of popular analytics platforms below, but we +#' I include a few examples of popular analytics platforms below, but we #' recommend getting the HTML directly from the tool: #' #' * [plausible.io](https://plausible.io): @@ -470,7 +470,7 @@ build_site_local <- function(pkg = ".", } check_built_site(pkg) - + cli::cli_rule("Finished building pkgdown site for package {.pkg {pkg$package}}") preview_site(pkg, preview = preview) } diff --git a/man/build_site.Rd b/man/build_site.Rd index e79c04b04..40d6be4ba 100644 --- a/man/build_site.Rd +++ b/man/build_site.Rd @@ -88,7 +88,7 @@ whole site. It specifies where the site will be published and is used to allow other pkgdown sites to link to your site when needed (\code{vignette("linking")}), generate a \code{sitemap.xml}, automatically generate a \code{CNAME} when -\link[=deploy_site_github]{deploying to github}, generate the metadata needed +\link[=build_site_github_pages]{deploying to github}, generate the metadata needed rich social "media cards" (\code{vignette("metadata")}), and more. \item \code{title} overrides the default site title, which is the package name. It's used in the page title and default navbar. diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 7d3366acc..2b3b9fb5c 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -9,9 +9,9 @@ authors: Maëlle Salmon: href: https://masalmon.eu Hadley Wickham: - href: http://hadley.nz + href: https://hadley.nz Posit Software, PBC: - href: https://www.posit.co + href: https://posit.co html: >- Posit @@ -65,7 +65,6 @@ reference: contents: - starts_with("deploy_") - build_site_github_pages - - check_pkgdown - title: Templates contents: From 25dcf2b0ea6a7a4ff37043b4995859c48b6f3d4c Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:43:29 -0400 Subject: [PATCH 02/17] Document init_site and build_favicons together. (build_favicons is more init_favicons() I guess? Also move `init_site()` / `build_favicons()` out of the build section (build section === site components) --- R/build-favicons.R | 15 ++++----------- R/init.R | 14 +++++++++++--- man/build_favicons.Rd | 27 --------------------------- man/init_site.Rd | 21 ++++++++++++++++++++- pkgdown/_pkgdown.yml | 9 +++++---- 5 files changed, 40 insertions(+), 46 deletions(-) delete mode 100644 man/build_favicons.Rd diff --git a/R/build-favicons.R b/R/build-favicons.R index 8bdca8f5b..0360632ee 100644 --- a/R/build-favicons.R +++ b/R/build-favicons.R @@ -1,20 +1,13 @@ -#' Create favicons from package logo +#' @details #' -#' This function auto-detects the location of your package logo (with the name -#' `logo.svg` (recommended format) or `logo.png`) and runs it through the -#' API to build a complete set of favicons -#' with different sizes, as needed for modern web usage. -#' -#' You only need to run the function once. The favicon set will be stored in -#' `pkgdown/favicon` and copied by [init_site()] to the relevant location when +#' You only need to run `build_favicons()` once. The favicon set will be stored in +#' `pkgdown/favicon` and copied by `init_site()` to the relevant location when #' the website is rebuilt. #' -#' Once complete, you should add `pkgdown/` to `.Rbuildignore ` to avoid a NOTE -#' during package checking. -#' #' @inheritParams as_pkgdown #' @param overwrite If `TRUE`, re-create favicons from package logo. #' @export +#' @rdname init_site build_favicons <- function(pkg = ".", overwrite = FALSE) { rlang::check_installed("openssl") pkg <- as_pkgdown(pkg) diff --git a/R/init.R b/R/init.R index 4597fc310..25ee8d181 100644 --- a/R/init.R +++ b/R/init.R @@ -8,6 +8,13 @@ #' * copies CSS/JS assets and extra files, and #' * runs `build_favicons()`, if needed. #' +#' `build_favicons()`: +#' * creates favicons from package logo. +#' * auto-detects the location of your package logo (with the name `logo.svg` +#' (recommended format) or `logo.png`) +#' * runs it through the API to build a complete +#' set of favicons with different sizes, as needed for modern web usage. +#' #' See `vignette("customise")` for the various ways you can customise the #' display of your site. #' @@ -20,6 +27,7 @@ #' #' @inheritParams build_articles #' @export +#' @order 1 init_site <- function(pkg = ".") { pkg <- as_pkgdown(pkg) @@ -59,8 +67,8 @@ copy_assets <- function(pkg = ".") { # pkgdown assets if (!identical(template$default_assets, FALSE)) { copy_asset_dir( - pkg, - path_pkgdown(paste0("BS", pkg$bs_version, "/", "assets")), + pkg, + path_pkgdown(paste0("BS", pkg$bs_version, "/", "assets")), src_root = path_pkgdown(), src_label = "/" ) @@ -69,7 +77,7 @@ copy_assets <- function(pkg = ".") { # package assets if (!is.null(template$package)) { copy_asset_dir( - pkg, + pkg, path_package_pkgdown("assets", template$package, pkg$bs_version), src_root = system_file(package = template$package), src_label = paste0("<", template$package, ">/") diff --git a/man/build_favicons.Rd b/man/build_favicons.Rd deleted file mode 100644 index 245393ebf..000000000 --- a/man/build_favicons.Rd +++ /dev/null @@ -1,27 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/build-favicons.R -\name{build_favicons} -\alias{build_favicons} -\title{Create favicons from package logo} -\usage{ -build_favicons(pkg = ".", overwrite = FALSE) -} -\arguments{ -\item{pkg}{Path to package.} - -\item{overwrite}{If \code{TRUE}, re-create favicons from package logo.} -} -\description{ -This function auto-detects the location of your package logo (with the name -\code{logo.svg} (recommended format) or \code{logo.png}) and runs it through the -\url{https://realfavicongenerator.net} API to build a complete set of favicons -with different sizes, as needed for modern web usage. -} -\details{ -You only need to run the function once. The favicon set will be stored in -\code{pkgdown/favicon} and copied by \code{\link[=init_site]{init_site()}} to the relevant location when -the website is rebuilt. - -Once complete, you should add \verb{pkgdown/} to \code{.Rbuildignore } to avoid a NOTE -during package checking. -} diff --git a/man/init_site.Rd b/man/init_site.Rd index 7d638ddf6..98f36e180 100644 --- a/man/init_site.Rd +++ b/man/init_site.Rd @@ -1,13 +1,18 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/init.R +% Please edit documentation in R/init.R, R/build-favicons.R \name{init_site} \alias{init_site} +\alias{build_favicons} \title{Initialise site infrastructure} \usage{ init_site(pkg = ".") + +build_favicons(pkg = ".", overwrite = FALSE) } \arguments{ \item{pkg}{Path to package.} + +\item{overwrite}{If \code{TRUE}, re-create favicons from package logo.} } \description{ \code{init_site()}: @@ -18,9 +23,23 @@ init_site(pkg = ".") \item runs \code{build_favicons()}, if needed. } +\code{build_favicons()}: +\itemize{ +\item creates favicons from package logo. +\item auto-detects the location of your package logo (with the name \code{logo.svg} +(recommended format) or \code{logo.png}) +\item runs it through the \url{https://realfavicongenerator.net} API to build a complete +set of favicons with different sizes, as needed for modern web usage. +} + See \code{vignette("customise")} for the various ways you can customise the display of your site. } +\details{ +You only need to run \code{build_favicons()} once. The favicon set will be stored in +\code{pkgdown/favicon} and copied by \code{init_site()} to the relevant location when +the website is rebuilt. +} \section{Build-ignored files}{ We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}} to build-ignore \verb{docs/} and \verb{_pkgdown.yml}. If use another directory, or create the site manually, diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 2b3b9fb5c..0038c57ac 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -51,18 +51,19 @@ articles: - starts_with("test") reference: -- title: Build +- title: Site components desc: Build a complete site or one of its components. contents: - build_site - starts_with("build_") - -build_site_github_pages - - init_site - - preview_site - pkgdown_sitrep -- title: Deployment +- title: Deployment and Build + desc: Build or deploy the full site. contents: + - init_site + - preview_site - starts_with("deploy_") - build_site_github_pages From 501fcb1e1496ce6000dcddbd2fe47f8e942e5fe8 Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:47:38 -0400 Subject: [PATCH 03/17] Document `build_home()`, before `build_home_index()` --- R/build-home.R | 215 +++++++++++++++++++++++----------------------- man/build_home.Rd | 16 ++-- 2 files changed, 116 insertions(+), 115 deletions(-) diff --git a/R/build-home.R b/R/build-home.R index 8c085e59c..0033b4d61 100644 --- a/R/build-home.R +++ b/R/build-home.R @@ -15,40 +15,40 @@ #' iterating when experimenting with site styles. #' #' # Home page -#' +#' #' The main content of the home page (`index.html`) is generated from #' `pkgdown/index.md`, `index.md`, or `README.md`, in that order. -#' Most packages will use `README.md` because that's also displayed by GitHub -#' and CRAN. Use `index.md` if you want your package website to look -#' different to your README, and use `pkgdown/index.md` if you don't want that +#' Most packages will use `README.md` because that's also displayed by GitHub +#' and CRAN. Use `index.md` if you want your package website to look +#' different to your README, and use `pkgdown/index.md` if you don't want that #' file to live in your package root directory. -#' -#' If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit -#' the document to create the corresponding `.md`. pkgdown does not do this +#' +#' If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit +#' the document to create the corresponding `.md`. pkgdown does not do this #' for you because it only touches files in the `doc/` directory. -#' -#' Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in +#' +#' Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in #' `.github/` (e.g. `CODE_OF_CONDUCT.md`) are copied by `build_home()` to `docs/` and converted to HTML. -#' -#' The home page also features a sidebar with information extracted from the -#' package. You can tweak it via the configuration file, to help make the home +#' +#' The home page also features a sidebar with information extracted from the +#' package. You can tweak it via the configuration file, to help make the home #' page an as informative as possible landing page. -#' +#' #' ## Images and figures -#' -#' If you want to include images in your `README.md`, they must be stored +#' +#' If you want to include images in your `README.md`, they must be stored #' somewhere in the package so that they can be displayed on the CRAN website. -#' The best place to put them is `man/figures`. If you are generating figures +#' The best place to put them is `man/figures`. If you are generating figures #' with R Markdown, make sure you set up `fig.path` as followed: -#' +#' #' ``` r #' knitr::opts_chunk$set( #' fig.path = "man/figures/" #' ) #' ``` -#' +#' #' This should usually go in a chunk with `include = FALSE`. -#' +#' #' ```` markdown #' ```{r chunk-name, include=FALSE}`r ''` #' knitr::opts_chunk$set( @@ -56,27 +56,27 @@ #' ) #' ``` #' ```` -#' +#' #' ## Package logo -#' +#' #' If you have a package logo, you can include it at the top of your README #' in a level-one heading: -#' +#' #' ``` markdown #' # pkgdown #' ``` -#' +#' #' [init_site()] will also automatically create a favicon set from your package logo. -#' +#' #' ## YAML config - title and description -#' +#' #' By default, the page title and description are extracted automatically from #' the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes -#' off quoted words). CRAN ensures that these fields don't contain phrases -#' like "R package" because that's obvious on CRAN. To make your package more -#' findable on search engines, it's good practice to override the `title` and +#' off quoted words). CRAN ensures that these fields don't contain phrases +#' like "R package" because that's obvious on CRAN. To make your package more +#' findable on search engines, it's good practice to override the `title` and #' `description`, thinking about what people might search for: -#' +#' #' ```yaml #' home: #' title: An R package for pool-noodle discovery @@ -85,45 +85,45 @@ #' using this package to automatically discover and add pool-noodles #' to your growing collection. #' ``` -#' -#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of +#' +#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of #' writing paragraphs of text.) -#' +#' #' ## Dev badges -#' +#' #' pkgdown identifies badges in three ways: -#' -#' - Any image-containing links between `` and -#' ``, as e.g. created by `usethis::use_readme_md()` -#' or `usethis::use_readme_rmd()`. There should always be an empty line after -#' the `` line. If you divide badges into paragraphs, +#' +#' - Any image-containing links between `` and +#' ``, as e.g. created by `usethis::use_readme_md()` +#' or `usethis::use_readme_rmd()`. There should always be an empty line after +#' the `` line. If you divide badges into paragraphs, #' make sure to add an empty line before the `` line. -#' +#' #' - Any image-containing links within `
`. -#' +#' #' - Within the first paragraph, if it only contains image-containing links. -#' +#' #' Identified badges are **removed** from the _main content_. #' They are shown or not in the _sidebar_ depending on the development mode and #' sidebar customization, see the sidebar section. -#' +#' #' # Authors -#' +#' #' By default, pkgdown will display author information in three places: -#' +#' #' * the sidebar, #' * the left part side of the footer, #' * the author page. -#' -#' This documentation describes how to customise the overall author display. -#' See `?build_home` and `?build_site` for details about changing the location +#' +#' This documentation describes how to customise the overall author display. +#' See `?build_home` and `?build_site` for details about changing the location #' of the authors information within the home sidebar and the site footer. -#' +#' #' ## Authors ORCID and bio -#' -#' Author ORCID identification numbers in the `DESCRIPTION` are linked using +#' +#' Author ORCID identification numbers in the `DESCRIPTION` are linked using #' the ORCID logo: -#' +#' #' ```r #' Authors@R: c( #' person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), @@ -134,11 +134,11 @@ #' ) #' ) #' ``` -#' -#' If you want to add more details about authors or their involvement with the -#' package, you can use the comment field, which will be rendered on the +#' +#' If you want to add more details about authors or their involvement with the +#' package, you can use the comment field, which will be rendered on the #' authors page. -#' +#' #' ```r #' Authors@R: c( #' person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), @@ -149,49 +149,49 @@ #' ) #' ) #' ``` -#' +#' #' ## Additional control via YAML -#' -#' You can control additinal aspects of the authors display via the `authors` +#' +#' You can control additinal aspects of the authors display via the `authors` #' YAML field: -#' +#' #' * display of each author in the footer, sidebar and authors page, #' * which authors (by role) are displayed in the sidebar and footer, -#' * text before authors in the footer, +#' * text before authors in the footer, #' * text before and after authors in the sidebar, #' * text before and after authors on the authors page. -#' -#' You can modify how each author's name is displayed by adding a subsection -#' for `authors`. Each entry in `authors` should be named the author's name +#' +#' You can modify how each author's name is displayed by adding a subsection +#' for `authors`. Each entry in `authors` should be named the author's name #' (matching `DESCRIPTION`) and can contain `href` and/or `html` fields: -#' +#' #' * If `href` is provided, the author's name will be linked to this URL. #' * If `html` is provided, it will be shown instead of the author's name. #' This is particularly useful if you want to display the logo of a corporate -#' sponsor. Use an absolute URL to an image, not a relative link. Use an empty -#' alternative text rather than no alternative text so a screen-reader would +#' sponsor. Use an absolute URL to an image, not a relative link. Use an empty +#' alternative text rather than no alternative text so a screen-reader would #' skip over it. -#' +#' #' ```yaml #' authors: #' firstname lastname: #' href: "http://name-website.com" #' html: "" #' ``` -#' -#' -#' By default, the "developers" list shown in the sidebar and footer is -#' populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") +#' +#' +#' By default, the "developers" list shown in the sidebar and footer is +#' populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") #' from the `DESCRIPTION`. You could choose other roles for filtering. #' With the configuration below: -#' -#' * only the maintainer and funder(s) appear in the footer, after the text +#' +#' * only the maintainer and funder(s) appear in the footer, after the text #' "Crafted by", #' * all authors and contributors appear in the sidebar, #' * the authors list on the sidebar is preceded and followed by some text, #' * the authors list on the authors page is preceded and followed by some text. -#' -#' +#' +#' #' ```yaml #' authors: #' footer: @@ -204,32 +204,32 @@ #' before: "This package is proudly brought to you by:" #' after: "See the [changelog](news/index.html) for other contributors. :pray:" #' ``` -#' -#' If you want to filter authors based on something else than their roles, -#' consider using a custom sidebar/footer component +#' +#' If you want to filter authors based on something else than their roles, +#' consider using a custom sidebar/footer component #' (see `?build_home`/`?build_site`, respectively). -#' +#' #' # Sidebar -#' +#' #' You can customise the homepage sidebar with the `home.sidebar` field. -#' It's made up of two pieces: `structure`, which defines the overall layout, -#' and `components`, which defines what each piece looks like. This organisation -#' makes it easy to mix and match the pkgdown defaults with your own +#' It's made up of two pieces: `structure`, which defines the overall layout, +#' and `components`, which defines what each piece looks like. This organisation +#' makes it easy to mix and match the pkgdown defaults with your own #' customisations. -#' +#' #' This is the default structure: -#' +#' #' ``` yaml #' home: #' sidebar: #' structure: [links, license, community, citation, authors, dev] #' ``` -#' +#' #' These are drawn from seven built-in components: -#' -#' - `links`: automated links generated from `URL` and `BugReports` fields +#' +#' - `links`: automated links generated from `URL` and `BugReports` fields #' from `DESCRIPTION` plus manual links from the `home.links` field: -#' +#' #' ``` yaml #' home: #' links: @@ -238,26 +238,26 @@ #' - text: Roadmap #' href: /roadmap.html #' ``` -#' -#' - `license`: Licensing information if `LICENSE`/`LICENCE` or +#' +#' - `license`: Licensing information if `LICENSE`/`LICENCE` or #' `LICENSE.md`/`LICENCE.md` files are present. -#' -#' - `community`: links to to `.github/CONTRIBUTING.md`, +#' +#' - `community`: links to to `.github/CONTRIBUTING.md`, #' `.github/CODE_OF_CONDUCT.md`, etc. -#' -#' - `citation`: link to package citation information. Uses either +#' +#' - `citation`: link to package citation information. Uses either #' `inst/CITATION` or, if absent, information from the `DESCRIPTION`. -#' +#' #' - `authors`: selected authors from the `DESCRIPTION`. -#' -#' - `dev`: development status badges extracted from `README.md`/`index.md`. -#' This is only shown for "development" versions of websites; see -#' "Development mode" in `?build_site` for details. -#' +#' +#' - `dev`: development status badges extracted from `README.md`/`index.md`. +#' This is only shown for "development" versions of websites; see +#' "Development mode" in `?build_site` for details. +#' #' - `toc`: a table of contents for the README (not shown by default). -#' +#' #' You can also add your own components, where `text` is markdown text: -#' +#' #' ``` yaml #' home: #' sidebar: @@ -267,23 +267,24 @@ #' title: Funding #' text: We are *grateful* for funding! #' ``` -#' +#' #' Alternatively, you can provide a ready-made sidebar HTML: -#' +#' #' ``` yaml #' home: #' sidebar: #' html: path-to-sidebar.html #' ``` -#' +#' #' Or completely remove it: -#' +#' #' ``` yaml #' home: #' sidebar: FALSE #' ``` #' @inheritParams build_articles #' @export +#' @order 1 build_home <- function(pkg = ".", override = list(), preview = NA, diff --git a/man/build_home.Rd b/man/build_home.Rd index a06f06596..ebf5c6c59 100644 --- a/man/build_home.Rd +++ b/man/build_home.Rd @@ -1,25 +1,25 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/build-home-index.R, R/build-home.R -\name{build_home_index} -\alias{build_home_index} +% Please edit documentation in R/build-home.R, R/build-home-index.R +\name{build_home} \alias{build_home} +\alias{build_home_index} \title{Build home section} \usage{ -build_home_index(pkg = ".", quiet = TRUE) - build_home(pkg = ".", override = list(), preview = NA, quiet = TRUE) + +build_home_index(pkg = ".", quiet = TRUE) } \arguments{ \item{pkg}{Path to package.} -\item{quiet}{Set to \code{FALSE} to display output of knitr and -pandoc. This is useful when debugging.} - \item{override}{An optional named list used to temporarily override values in \verb{_pkgdown.yml}} \item{preview}{If \code{TRUE}, or \code{is.na(preview) && interactive()}, will preview freshly generated section in browser.} + +\item{quiet}{Set to \code{FALSE} to display output of knitr and +pandoc. This is useful when debugging.} } \description{ \code{build_home()} function generates pages at the top-level of the site From 04bb7024197e307ca977e4e3cc646946180207c9 Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:52:58 -0400 Subject: [PATCH 04/17] Mention r-lib/tidyverse examples in README.md --- README.Rmd | 4 +++- README.md | 5 ++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/README.Rmd b/README.Rmd index b286a25e4..3218946ea 100644 --- a/README.Rmd +++ b/README.Rmd @@ -69,7 +69,7 @@ Then learn about the many new ways to customise your site in `vignette("customis ## In the wild -At last count, pkgdown is used [by over 11,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples created by contributors to pkgdown: +At last count, pkgdown is used [by over 11,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples: * [bayesplot](http://mc-stan.org/bayesplot/index.html) ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)): @@ -88,6 +88,8 @@ At last count, pkgdown is used [by over 11,000 packages](https://github.com/sear ([source](https://github.com/renozao/NMF)): a framework to perform non-negative matrix factorization (NMF). +* [tidyverse and r-lib packages source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code) + Comparing the source and output of these sites is a great way to learn new pkgdown techniques. ## Code of conduct diff --git a/README.md b/README.md index 6eb921abd..6db2d7cca 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Then learn about the many new ways to customise your site in At last count, pkgdown is used [by over 11,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). -Here are a few examples created by contributors to pkgdown: +Here are a few examples: - [bayesplot](http://mc-stan.org/bayesplot/index.html) ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)): @@ -103,6 +103,9 @@ Here are a few examples created by contributors to pkgdown: ([source](https://github.com/renozao/NMF)): a framework to perform non-negative matrix factorization (NMF). +- [tidyverse and r-lib packages + source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code) + Comparing the source and output of these sites is a great way to learn new pkgdown techniques. From 2e812a244896e88f87c9e34a3704d22000cd385e Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:54:32 -0400 Subject: [PATCH 05/17] Mention `usethis::use_article()` (possibly remove more of that Rbuildignore info?) --- R/build-articles.R | 9 +++++---- man/build_articles.Rd | 3 ++- vignettes/pkgdown.Rmd | 6 ++++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/R/build-articles.R b/R/build-articles.R index 1b56b752e..a5b41f11e 100644 --- a/R/build-articles.R +++ b/R/build-articles.R @@ -88,9 +88,9 @@ #' #' ## Missing topics #' -#' pkgdown will warn if there are (non-internal) articles that aren't listed -#' in the articles index. You can suppress such warnings by listing the -#' affected articles in a section with `title: internal` (case sensitive); +#' pkgdown will warn if there are (non-internal) articles that aren't listed +#' in the articles index. You can suppress such warnings by listing the +#' affected articles in a section with `title: internal` (case sensitive); #' this section will not be displayed on the index page. #' #' # External files @@ -156,7 +156,8 @@ #' Additionally, htmlwidgets do not work when `as_is: true`. #' #' # Suppressing vignettes -#' If you want articles that are not vignettes, either put them in +#' If you want [articles](https://r-pkgs.org/vignettes.html#sec-vignettes-article) +#' that are not vignettes, use `usethis::use_article()` either put them in #' subdirectories or list in `.Rbuildignore`. An articles link will be #' automatically added to the default navbar if the vignettes directory is #' present: if you do not want this, you will need to customise the navbar. See diff --git a/man/build_articles.Rd b/man/build_articles.Rd index f77c93555..2abd8b153 100644 --- a/man/build_articles.Rd +++ b/man/build_articles.Rd @@ -209,7 +209,8 @@ Additionally, htmlwidgets do not work when \code{as_is: true}. } \section{Suppressing vignettes}{ -If you want articles that are not vignettes, either put them in +If you want \href{https://r-pkgs.org/vignettes.html#sec-vignettes-article}{articles} +that are not vignettes, use \code{usethis::use_article()} either put them in subdirectories or list in \code{.Rbuildignore}. An articles link will be automatically added to the default navbar if the vignettes directory is present: if you do not want this, you will need to customise the navbar. See diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index 7d7e3324d..6324b7db2 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -134,10 +134,12 @@ It just re-builds the index page, making it faster to quickly change `_pkgdown.y ## Articles pkgdown will automatically build all vignettes found in `vignettes/`, translating them to HTML files in `articles/`. -Due to the way that pkgdown has to integrate RMarkdown generated HTML with its own HTML, relatively little control is available over the output format. +It is recommended to name your intro article with your package name to generate a Get Started page automatically. + +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). +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 also `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. ## News From 8ec5a3df99fcc937618644f97211f7c3e9af9a53 Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:55:26 -0400 Subject: [PATCH 06/17] Mention gh pages first + avoid mentioning Twitter. --- vignettes/pkgdown.Rmd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index 6324b7db2..d5b30b424 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -170,10 +170,10 @@ See `?build_news` for more customisation options including how to: If you use GitHub, there are two ways to publish your site on GitHub Pages: -- Build the site locally, check in the docs directory, then configure GitHub Pages to [use that directory](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - - 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()`. + 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). + +- Build the site locally, check in the docs directory, then configure GitHub Pages to [use that directory](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). ## Promoting @@ -189,4 +189,4 @@ Once your finalized site is built and published on the web, you should publicize (`usethis::use_pkgdown_github_pages()` does this for you.) -3. On Twitter (make sure to include `#rstats`). +3. On social media (make sure to include `#rstats`). From 696e9b405195af68fc987e069a5b913534e096b5 Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:55:50 -0400 Subject: [PATCH 07/17] Link to vignette in `build_search()` --- R/build-search-docs.R | 4 ++-- man/build_search.Rd | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/R/build-search-docs.R b/R/build-search-docs.R index 6711edcef..244448ba1 100644 --- a/R/build-search-docs.R +++ b/R/build-search-docs.R @@ -39,7 +39,7 @@ build_sitemap <- function(pkg = ".") { doc <- xml2::read_xml( paste0("") ) - + url_nodes <- unwrap_purrr_error(purrr::map(urls, url_node)) for (url in url_nodes) { xml2::xml_add_child(doc, url) @@ -88,7 +88,7 @@ url_node <- function(url) { #' #' @inheritParams build_articles #' @export -#' +#' @seealso `vignette("search")` build_search <- function(pkg = ".", override = list()) { pkg <- section_init(pkg, depth = 1L, override = override) diff --git a/man/build_search.Rd b/man/build_search.Rd index 4d2fc04fe..563304a1d 100644 --- a/man/build_search.Rd +++ b/man/build_search.Rd @@ -34,3 +34,6 @@ common issues such as the absence of URL in the pkgdown configuration file of your package. } +\seealso{ +\code{vignette("search")} +} From 521f91e5397562fc52551bbe49649cc838e03af8 Mon Sep 17 00:00:00 2001 From: olivroy Date: Mon, 20 May 2024 11:56:39 -0400 Subject: [PATCH 08/17] Add some text descriptions --- pkgdown/_pkgdown.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 0038c57ac..867c95f7f 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -52,7 +52,8 @@ articles: reference: - title: Site components - desc: Build a complete site or one of its components. + desc: Build a complete site or one of its components. See `vignette("pkgdown")` + for an overview of site components. contents: - build_site - starts_with("build_") @@ -60,7 +61,7 @@ reference: - pkgdown_sitrep - title: Deployment and Build - desc: Build or deploy the full site. + desc: Build or deploy the site. contents: - init_site - preview_site @@ -68,6 +69,7 @@ reference: - build_site_github_pages - title: Templates + desc: Helpers to create and preview templates. contents: - template_navbar - render_page From 8766f6452974f06d1747349bdd90928e7223a539 Mon Sep 17 00:00:00 2001 From: olivroy Date: Tue, 21 May 2024 07:13:46 -0400 Subject: [PATCH 09/17] Take suggestions --- R/build-search-docs.R | 2 +- pkgdown/_pkgdown.yml | 6 ++++-- vignettes/pkgdown.Rmd | 4 +--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/R/build-search-docs.R b/R/build-search-docs.R index 244448ba1..2b97a3a7c 100644 --- a/R/build-search-docs.R +++ b/R/build-search-docs.R @@ -88,7 +88,7 @@ url_node <- function(url) { #' #' @inheritParams build_articles #' @export -#' @seealso `vignette("search")` +#' build_search <- function(pkg = ".", override = list()) { pkg <- section_init(pkg, depth = 1L, override = override) diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 867c95f7f..5f58dc49f 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -53,17 +53,18 @@ articles: reference: - title: Site components desc: Build a complete site or one of its components. See `vignette("pkgdown")` - for an overview of site components. + for an overview. contents: - build_site + - init_site - starts_with("build_") - -build_site_github_pages + - -build_favicons - pkgdown_sitrep - title: Deployment and Build desc: Build or deploy the site. contents: - - init_site - preview_site - starts_with("deploy_") - build_site_github_pages @@ -76,6 +77,7 @@ reference: - title: Helpers contents: + - build_favicons - clean_site - rd2html - as_pkgdown diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index d5b30b424..71eac8e28 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -139,7 +139,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 also `usethis::use_article()` for an automated way to do this. +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. ## News @@ -173,8 +173,6 @@ 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). -- Build the site locally, check in the docs directory, then configure GitHub Pages to [use that directory](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - ## Promoting Once your finalized site is built and published on the web, you should publicize its URL in a few places: From e40d7b0f52256190b2e01dcf1ac23c6ba36783a0 Mon Sep 17 00:00:00 2001 From: olivroy Date: Tue, 21 May 2024 07:16:37 -0400 Subject: [PATCH 10/17] Revert documenting build_favicons and init_site() together. --- R/build-favicons.R | 15 +++++++++++---- R/init.R | 14 +++----------- man/build_favicons.Rd | 27 +++++++++++++++++++++++++++ man/build_search.Rd | 3 --- man/init_site.Rd | 21 +-------------------- man/pkgdown-package.Rd | 2 +- pkgdown/_pkgdown.yml | 2 +- 7 files changed, 44 insertions(+), 40 deletions(-) create mode 100644 man/build_favicons.Rd diff --git a/R/build-favicons.R b/R/build-favicons.R index 0360632ee..8bdca8f5b 100644 --- a/R/build-favicons.R +++ b/R/build-favicons.R @@ -1,13 +1,20 @@ -#' @details +#' Create favicons from package logo #' -#' You only need to run `build_favicons()` once. The favicon set will be stored in -#' `pkgdown/favicon` and copied by `init_site()` to the relevant location when +#' This function auto-detects the location of your package logo (with the name +#' `logo.svg` (recommended format) or `logo.png`) and runs it through the +#' API to build a complete set of favicons +#' with different sizes, as needed for modern web usage. +#' +#' You only need to run the function once. The favicon set will be stored in +#' `pkgdown/favicon` and copied by [init_site()] to the relevant location when #' the website is rebuilt. #' +#' Once complete, you should add `pkgdown/` to `.Rbuildignore ` to avoid a NOTE +#' during package checking. +#' #' @inheritParams as_pkgdown #' @param overwrite If `TRUE`, re-create favicons from package logo. #' @export -#' @rdname init_site build_favicons <- function(pkg = ".", overwrite = FALSE) { rlang::check_installed("openssl") pkg <- as_pkgdown(pkg) diff --git a/R/init.R b/R/init.R index 25ee8d181..4597fc310 100644 --- a/R/init.R +++ b/R/init.R @@ -8,13 +8,6 @@ #' * copies CSS/JS assets and extra files, and #' * runs `build_favicons()`, if needed. #' -#' `build_favicons()`: -#' * creates favicons from package logo. -#' * auto-detects the location of your package logo (with the name `logo.svg` -#' (recommended format) or `logo.png`) -#' * runs it through the API to build a complete -#' set of favicons with different sizes, as needed for modern web usage. -#' #' See `vignette("customise")` for the various ways you can customise the #' display of your site. #' @@ -27,7 +20,6 @@ #' #' @inheritParams build_articles #' @export -#' @order 1 init_site <- function(pkg = ".") { pkg <- as_pkgdown(pkg) @@ -67,8 +59,8 @@ copy_assets <- function(pkg = ".") { # pkgdown assets if (!identical(template$default_assets, FALSE)) { copy_asset_dir( - pkg, - path_pkgdown(paste0("BS", pkg$bs_version, "/", "assets")), + pkg, + path_pkgdown(paste0("BS", pkg$bs_version, "/", "assets")), src_root = path_pkgdown(), src_label = "/" ) @@ -77,7 +69,7 @@ copy_assets <- function(pkg = ".") { # package assets if (!is.null(template$package)) { copy_asset_dir( - pkg, + pkg, path_package_pkgdown("assets", template$package, pkg$bs_version), src_root = system_file(package = template$package), src_label = paste0("<", template$package, ">/") diff --git a/man/build_favicons.Rd b/man/build_favicons.Rd new file mode 100644 index 000000000..245393ebf --- /dev/null +++ b/man/build_favicons.Rd @@ -0,0 +1,27 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/build-favicons.R +\name{build_favicons} +\alias{build_favicons} +\title{Create favicons from package logo} +\usage{ +build_favicons(pkg = ".", overwrite = FALSE) +} +\arguments{ +\item{pkg}{Path to package.} + +\item{overwrite}{If \code{TRUE}, re-create favicons from package logo.} +} +\description{ +This function auto-detects the location of your package logo (with the name +\code{logo.svg} (recommended format) or \code{logo.png}) and runs it through the +\url{https://realfavicongenerator.net} API to build a complete set of favicons +with different sizes, as needed for modern web usage. +} +\details{ +You only need to run the function once. The favicon set will be stored in +\code{pkgdown/favicon} and copied by \code{\link[=init_site]{init_site()}} to the relevant location when +the website is rebuilt. + +Once complete, you should add \verb{pkgdown/} to \code{.Rbuildignore } to avoid a NOTE +during package checking. +} diff --git a/man/build_search.Rd b/man/build_search.Rd index 563304a1d..4d2fc04fe 100644 --- a/man/build_search.Rd +++ b/man/build_search.Rd @@ -34,6 +34,3 @@ common issues such as the absence of URL in the pkgdown configuration file of your package. } -\seealso{ -\code{vignette("search")} -} diff --git a/man/init_site.Rd b/man/init_site.Rd index 98f36e180..7d638ddf6 100644 --- a/man/init_site.Rd +++ b/man/init_site.Rd @@ -1,18 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/init.R, R/build-favicons.R +% Please edit documentation in R/init.R \name{init_site} \alias{init_site} -\alias{build_favicons} \title{Initialise site infrastructure} \usage{ init_site(pkg = ".") - -build_favicons(pkg = ".", overwrite = FALSE) } \arguments{ \item{pkg}{Path to package.} - -\item{overwrite}{If \code{TRUE}, re-create favicons from package logo.} } \description{ \code{init_site()}: @@ -23,23 +18,9 @@ build_favicons(pkg = ".", overwrite = FALSE) \item runs \code{build_favicons()}, if needed. } -\code{build_favicons()}: -\itemize{ -\item creates favicons from package logo. -\item auto-detects the location of your package logo (with the name \code{logo.svg} -(recommended format) or \code{logo.png}) -\item runs it through the \url{https://realfavicongenerator.net} API to build a complete -set of favicons with different sizes, as needed for modern web usage. -} - See \code{vignette("customise")} for the various ways you can customise the display of your site. } -\details{ -You only need to run \code{build_favicons()} once. The favicon set will be stored in -\code{pkgdown/favicon} and copied by \code{init_site()} to the relevant location when -the website is rebuilt. -} \section{Build-ignored files}{ We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}} to build-ignore \verb{docs/} and \verb{_pkgdown.yml}. If use another directory, or create the site manually, diff --git a/man/pkgdown-package.Rd b/man/pkgdown-package.Rd index 0a833e0db..5c411d2e2 100644 --- a/man/pkgdown-package.Rd +++ b/man/pkgdown-package.Rd @@ -13,7 +13,7 @@ Generate an attractive and useful website from a source package. 'pkgdown' conve \seealso{ Useful links: \itemize{ - \item \url{https://pkgdown.r-lib.org} + \item \url{https://pkgdown.r-lib.org/} \item \url{https://github.com/r-lib/pkgdown} \item Report bugs at \url{https://github.com/r-lib/pkgdown/issues} } diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 5f58dc49f..f681db8e6 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -56,7 +56,7 @@ reference: for an overview. contents: - build_site - - init_site + - init_site - starts_with("build_") - -build_site_github_pages - -build_favicons From 9ba9bc42bd61c7de166af3d5fcaa98ce5fc4328a Mon Sep 17 00:00:00 2001 From: olivroy Date: Sun, 2 Jun 2024 11:32:47 -0400 Subject: [PATCH 11/17] correct urls --- pkgdown/_pkgdown.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 86caadb70..faa95c5a9 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -9,9 +9,9 @@ authors: Maëlle Salmon: href: https://masalmon.eu Hadley Wickham: - href: http://hadley.nz + href: https://hadley.nz Posit Software, PBC: - href: https://www.posit.co + href: https://posit.co html: >- Posit @@ -67,6 +67,7 @@ reference: - starts_with("build_") - -build_site - -build_site_github_pages + - -build_favicons - init_site - subtitle: Customisation @@ -86,6 +87,7 @@ reference: - as_pkgdown - in_pkgdown - render_page + - build_favicons - title: Regression tests contents: From f3cf62bbb37351880c3caacc7658b1cf9ae13218 Mon Sep 17 00:00:00 2001 From: olivroy Date: Tue, 4 Jun 2024 12:40:10 -0400 Subject: [PATCH 12/17] Advertise more `has_concept()` by using it! + add `@family site components` --- R/build-articles.R | 1 + R/build-home.R | 1 + R/build-news.R | 1 + R/build-reference.R | 1 + R/build-tutorials.R | 1 + man/build_articles.Rd | 8 ++++++++ man/build_home.Rd | 8 ++++++++ man/build_news.Rd | 7 +++++++ man/build_reference.Rd | 8 ++++++++ man/build_tutorials.Rd | 8 ++++++++ vignettes/pkgdown.Rmd | 2 +- 11 files changed, 45 insertions(+), 1 deletion(-) diff --git a/R/build-articles.R b/R/build-articles.R index 5fdb09757..68bc53571 100644 --- a/R/build-articles.R +++ b/R/build-articles.R @@ -181,6 +181,7 @@ #' [build_site()] details. #' #' @inheritSection build_reference Figures +#' @family site components #' #' @inheritParams as_pkgdown #' @param quiet Set to `FALSE` to display output of knitr and diff --git a/R/build-home.R b/R/build-home.R index 245496e1d..142378b33 100644 --- a/R/build-home.R +++ b/R/build-home.R @@ -283,6 +283,7 @@ #' sidebar: FALSE #' ``` #' @inheritParams build_articles +#' @family site components #' @export #' @order 1 build_home <- function(pkg = ".", diff --git a/R/build-news.R b/R/build-news.R index 14b7e4cae..c61c9753e 100644 --- a/R/build-news.R +++ b/R/build-news.R @@ -66,6 +66,7 @@ #' news: #' cran_dates: false #' ``` +#' @family site components #' #' @seealso [Tidyverse style for News](https://style.tidyverse.org/news.html) #' diff --git a/R/build-reference.R b/R/build-reference.R index 87c425151..e7529d5ed 100644 --- a/R/build-reference.R +++ b/R/build-reference.R @@ -136,6 +136,7 @@ #' as HTML widgets. #' #' @inheritParams build_articles +#' @family site components #' @param lazy If `TRUE`, only rebuild pages where the `.Rd` #' is more recent than the `.html`. This makes it much easier to #' rapidly prototype. It is set to `FALSE` by [build_site()]. diff --git a/R/build-tutorials.R b/R/build-tutorials.R index 69ed969d9..1060a3e87 100644 --- a/R/build-tutorials.R +++ b/R/build-tutorials.R @@ -26,6 +26,7 @@ #' url: https://jjallaire.shinyapps.io/learnr-tutorial-01-data-basics/ #' ``` #' @inheritParams build_articles +#' @family site components #' @export build_tutorials <- function(pkg = ".", override = list(), preview = NA) { pkg <- section_init(pkg, depth = 1L, override = override) diff --git a/man/build_articles.Rd b/man/build_articles.Rd index ef2b229f9..974cfe245 100644 --- a/man/build_articles.Rd +++ b/man/build_articles.Rd @@ -258,3 +258,11 @@ that will be available to custom graphics output devices such as HTML widgets. } +\seealso{ +Other site components: +\code{\link{build_home}()}, +\code{\link{build_news}()}, +\code{\link{build_reference}()}, +\code{\link{build_tutorials}()} +} +\concept{site components} diff --git a/man/build_home.Rd b/man/build_home.Rd index ebf5c6c59..224f4b5c6 100644 --- a/man/build_home.Rd +++ b/man/build_home.Rd @@ -292,3 +292,11 @@ Or completely remove it: }\if{html}{\out{}} } +\seealso{ +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_news}()}, +\code{\link{build_reference}()}, +\code{\link{build_tutorials}()} +} +\concept{site components} diff --git a/man/build_news.Rd b/man/build_news.Rd index 4da4a3196..73f2d24f7 100644 --- a/man/build_news.Rd +++ b/man/build_news.Rd @@ -81,4 +81,11 @@ Suppress the default addition of CRAN release dates with: \seealso{ \href{https://style.tidyverse.org/news.html}{Tidyverse style for News} + +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_home}()}, +\code{\link{build_reference}()}, +\code{\link{build_tutorials}()} } +\concept{site components} diff --git a/man/build_reference.Rd b/man/build_reference.Rd index 064a413fb..9067052cf 100644 --- a/man/build_reference.Rd +++ b/man/build_reference.Rd @@ -189,3 +189,11 @@ that will be available to custom graphics output devices such as HTML widgets. } +\seealso{ +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_home}()}, +\code{\link{build_news}()}, +\code{\link{build_tutorials}()} +} +\concept{site components} diff --git a/man/build_tutorials.Rd b/man/build_tutorials.Rd index 1d7abe923..cebe6612f 100644 --- a/man/build_tutorials.Rd +++ b/man/build_tutorials.Rd @@ -43,3 +43,11 @@ section. This should be a list where each element specifies: }\if{html}{\out{}} } +\seealso{ +Other site components: +\code{\link{build_articles}()}, +\code{\link{build_home}()}, +\code{\link{build_news}()}, +\code{\link{build_reference}()} +} +\concept{site components} diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index f14db7d25..ea2291b7e 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -105,7 +105,7 @@ reference: Note the use of `starts_with()` to select all functions with a common prefix. You can also use `ends_with()` and `matches()`. -See complete details in `?build_reference`. +See complete details in `?build_reference`, including other topic matching helper functions. While iterating on the reference index you might want to run `pkgdown::build_reference_index()`. It just re-builds the index page, making it faster to quickly change `_pkgdown.yml` and see how it affects your site. From 8f3a2863d16bb8efd325c8b94f307931164a7a89 Mon Sep 17 00:00:00 2001 From: olivroy Date: Tue, 4 Jun 2024 13:07:44 -0400 Subject: [PATCH 13/17] Fix typos + add cross-references --- R/build-articles.R | 3 +-- R/build-favicons.R | 10 +++++----- R/build-reference.R | 2 +- man/build_articles.Rd | 3 +-- man/build_favicons.Rd | 10 +++++----- man/build_reference.Rd | 2 +- pkgdown/_pkgdown.yml | 8 ++++---- vignettes/translations.Rmd | 2 +- 8 files changed, 19 insertions(+), 21 deletions(-) diff --git a/R/build-articles.R b/R/build-articles.R index 68bc53571..38411d683 100644 --- a/R/build-articles.R +++ b/R/build-articles.R @@ -174,8 +174,7 @@ #' #' # Suppressing vignettes #' If you want [articles](https://r-pkgs.org/vignettes.html#sec-vignettes-article) -#' that are not vignettes, use `usethis::use_article()` either put them in -#' subdirectories or list in `.Rbuildignore`. An articles link will be +#' that are not vignettes, use `usethis::use_article()` to create it. An articles link will be #' automatically added to the default navbar if the vignettes directory is #' present: if you do not want this, you will need to customise the navbar. See #' [build_site()] details. diff --git a/R/build-favicons.R b/R/build-favicons.R index 252f7fa61..3b0c02c2c 100644 --- a/R/build-favicons.R +++ b/R/build-favicons.R @@ -1,16 +1,16 @@ -#' Create favicons from package logo +#' Initialise favicons from package logo #' #' This function auto-detects the location of your package logo (with the name -#' `logo.svg` (recommended format) or `logo.png`) and runs it through the -#' API to build a complete set of favicons -#' with different sizes, as needed for modern web usage. +#' `logo.svg` (recommended format) or `logo.png`, created with `usethis::use_logo()`) +#' and runs it through the API to build a +#' complete set of favicons with different sizes, as needed for modern web usage. #' #' You only need to run the function once. The favicon set will be stored in #' `pkgdown/favicon` and copied by [init_site()] to the relevant location when #' the website is rebuilt. #' #' Once complete, you should add `pkgdown/` to `.Rbuildignore ` to avoid a NOTE -#' during package checking. +#' during package checking. (`usethis::use_logo()` does this for you!) #' #' @inheritParams as_pkgdown #' @param overwrite If `TRUE`, re-create favicons from package logo. diff --git a/R/build-reference.R b/R/build-reference.R index e7529d5ed..16ad706af 100644 --- a/R/build-reference.R +++ b/R/build-reference.R @@ -83,7 +83,7 @@ #' * `has_lifecycle("deprecated")` will select all topics with lifecycle #' deprecated. #' -#' All functions (except for `has_keywords()`) automatically exclude internal +#' All functions (except for `has_keyword()`) automatically exclude internal #' topics (i.e. those with `\keyword{internal}`). You can choose to include #' with (e.g.) `starts_with("build_", internal = TRUE)`. #' diff --git a/man/build_articles.Rd b/man/build_articles.Rd index 974cfe245..e1d92d88e 100644 --- a/man/build_articles.Rd +++ b/man/build_articles.Rd @@ -228,8 +228,7 @@ Additionally, htmlwidgets do not work when \code{as_is: true}. \section{Suppressing vignettes}{ If you want \href{https://r-pkgs.org/vignettes.html#sec-vignettes-article}{articles} -that are not vignettes, use \code{usethis::use_article()} either put them in -subdirectories or list in \code{.Rbuildignore}. An articles link will be +that are not vignettes, use \code{usethis::use_article()} to create it. An articles link will be automatically added to the default navbar if the vignettes directory is present: if you do not want this, you will need to customise the navbar. See \code{\link[=build_site]{build_site()}} details. diff --git a/man/build_favicons.Rd b/man/build_favicons.Rd index 245393ebf..2b76a279b 100644 --- a/man/build_favicons.Rd +++ b/man/build_favicons.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/build-favicons.R \name{build_favicons} \alias{build_favicons} -\title{Create favicons from package logo} +\title{Initialise favicons from package logo} \usage{ build_favicons(pkg = ".", overwrite = FALSE) } @@ -13,9 +13,9 @@ build_favicons(pkg = ".", overwrite = FALSE) } \description{ This function auto-detects the location of your package logo (with the name -\code{logo.svg} (recommended format) or \code{logo.png}) and runs it through the -\url{https://realfavicongenerator.net} API to build a complete set of favicons -with different sizes, as needed for modern web usage. +\code{logo.svg} (recommended format) or \code{logo.png}, created with \code{usethis::use_logo()}) +and runs it through the \url{https://realfavicongenerator.net} API to build a +complete set of favicons with different sizes, as needed for modern web usage. } \details{ You only need to run the function once. The favicon set will be stored in @@ -23,5 +23,5 @@ You only need to run the function once. The favicon set will be stored in the website is rebuilt. Once complete, you should add \verb{pkgdown/} to \code{.Rbuildignore } to avoid a NOTE -during package checking. +during package checking. (\code{usethis::use_logo()} does this for you!) } diff --git a/man/build_reference.Rd b/man/build_reference.Rd index 9067052cf..93742339b 100644 --- a/man/build_reference.Rd +++ b/man/build_reference.Rd @@ -133,7 +133,7 @@ or \code{sass::font_face} (topic name). deprecated. } -All functions (except for \code{has_keywords()}) automatically exclude internal +All functions (except for \code{has_keyword()}) automatically exclude internal topics (i.e. those with \verb{\\keyword\{internal\}}). You can choose to include with (e.g.) \code{starts_with("build_", internal = TRUE)}. diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index d48d56265..4fd887896 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -63,10 +63,9 @@ reference: desc: These functions are useful for rapid iteration when you're working on a specific part of your site. contents: - - starts_with("build_") - - -build_site - - -build_site_github_pages - - -build_favicons + - has_concept("site components") + - build_search + - build_redirects - init_site - subtitle: Customisation @@ -98,6 +97,7 @@ reference: redirects: - ["articles/search.html", "reference/build_search.html"] +- ["articles/pkgdown.html#language", "articles/translations.html"] news: releases: diff --git a/vignettes/translations.Rmd b/vignettes/translations.Rmd index eccb08e04..394825b3f 100644 --- a/vignettes/translations.Rmd +++ b/vignettes/translations.Rmd @@ -92,5 +92,5 @@ Then commit your changes to Git and submit your pull request for review: ```{r} #| eval: false -usethis::pr_submit() +usethis::pr_push() ``` From c2a6389e01bea3dcece42c798a76d77b8b4049fc Mon Sep 17 00:00:00 2001 From: olivroy Date: Wed, 5 Jun 2024 10:28:23 -0400 Subject: [PATCH 14/17] 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 From b39085852d5bd7fac42968fb6d365f2383775bcc Mon Sep 17 00:00:00 2001 From: olivroy Date: Wed, 5 Jun 2024 10:28:36 -0400 Subject: [PATCH 15/17] Address comments --- R/build-favicons.R | 1 + man/build_favicons.Rd | 3 +-- pkgdown/_pkgdown.yml | 1 - 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/R/build-favicons.R b/R/build-favicons.R index 3b0c02c2c..1953ed811 100644 --- a/R/build-favicons.R +++ b/R/build-favicons.R @@ -1,5 +1,6 @@ #' Initialise favicons from package logo #' +#' @description #' This function auto-detects the location of your package logo (with the name #' `logo.svg` (recommended format) or `logo.png`, created with `usethis::use_logo()`) #' and runs it through the API to build a diff --git a/man/build_favicons.Rd b/man/build_favicons.Rd index 2b76a279b..678f60cfd 100644 --- a/man/build_favicons.Rd +++ b/man/build_favicons.Rd @@ -16,8 +16,7 @@ This function auto-detects the location of your package logo (with the name \code{logo.svg} (recommended format) or \code{logo.png}, created with \code{usethis::use_logo()}) and runs it through the \url{https://realfavicongenerator.net} API to build a complete set of favicons with different sizes, as needed for modern web usage. -} -\details{ + You only need to run the function once. The favicon set will be stored in \code{pkgdown/favicon} and copied by \code{\link[=init_site]{init_site()}} to the relevant location when the website is rebuilt. diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 4fd887896..f47693756 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -97,7 +97,6 @@ reference: redirects: - ["articles/search.html", "reference/build_search.html"] -- ["articles/pkgdown.html#language", "articles/translations.html"] news: releases: From e19108671dc512305b643e30d22bf1e2584843fc Mon Sep 17 00:00:00 2001 From: olivroy <52606734+olivroy@users.noreply.github.com> Date: Wed, 5 Jun 2024 10:31:03 -0400 Subject: [PATCH 16/17] Apply suggestions from code review Co-authored-by: Hadley Wickham --- README.Rmd | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.Rmd b/README.Rmd index 157fe0d4f..bee8ac3e6 100644 --- a/README.Rmd +++ b/README.Rmd @@ -67,7 +67,7 @@ Then learn about the many new ways to customise your site in `vignette("customis ## In the wild -At last count, pkgdown is used [by over 11,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples: +At last count, pkgdown is used [by over 12,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples: * [bayesplot](http://mc-stan.org/bayesplot/index.html) ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)): diff --git a/README.md b/README.md index 453954bc0..c8c32250e 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ Then learn about the many new ways to customise your site in ## In the wild -At last count, pkgdown is used [by over 11,000 +At last count, pkgdown is used [by over 12,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples: From 8bbf92e3ef7f8fe9374fa9ea5940dbf0e8f3e425 Mon Sep 17 00:00:00 2001 From: olivroy Date: Thu, 6 Jun 2024 07:54:26 -0400 Subject: [PATCH 17/17] Mention `build_site()` + move footnote. --- README.Rmd | 8 ++++++-- README.md | 9 +++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/README.Rmd b/README.Rmd index bee8ac3e6..b24dccae9 100644 --- a/README.Rmd +++ b/README.Rmd @@ -48,9 +48,13 @@ Get started with [usethis](https://usethis.r-lib.org/): usethis::use_pkgdown_github_pages() ``` +```{r, eval = FALSE} +# Preview your site locally before publishing +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 adds the necessary components and sets up GitHub Actions[^1] 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]: If you don't use GitHub, you can use `usethis::use_pkgdown()` + `pkgdown::build_site()` to create a website. diff --git a/README.md b/README.md index c8c32250e..0a820511c 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,15 @@ Get started with [usethis](https://usethis.r-lib.org/): usethis::use_pkgdown_github_pages() ``` -This adds the necessary components and sets up GitHub Actions for +``` r +# Preview your site locally before publishing +pkgdown::build_site() +``` + +This adds the necessary components and sets up GitHub Actions[^1] 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] +vignettes will be rendered into `articles/`. ### pkgdown 2.0.0 and Bootstrap 5