Permalink
Cannot retrieve contributors at this time
#' Build a complete pkgdown website | |
#' | |
#' @description | |
#' `build_site()` is a convenient wrapper around six functions: | |
#' | |
#' * [init_site()] | |
#' * [build_home()] | |
#' * [build_reference()] | |
#' * [build_articles()] | |
#' * [build_tutorials()] | |
#' * [build_news()] | |
#' | |
#' See the documentation for the each function to learn how to control | |
#' that aspect of the site. | |
#' | |
#' Note if names of generated files were changed, you will need to use | |
#' [clean_site()] first to clean up orphan files. | |
#' | |
#' @section YAML config: | |
#' There are five top-level YAML settings that affect the entire site: | |
#' `destination`, `url`, `title`, `template`, and `navbar`. | |
#' | |
#' `destination` controls where the site will be generated. It defaults to | |
#' `docs/` (for GitHub pages), but you can override if desired. Relative | |
#' paths will be taken relative to the package root. | |
#' | |
#' `url` optionally specifies the url where the site will be published. | |
#' Supplying this will: | |
#' * Allow other pkgdown sites to link to your site when needed, | |
#' rather than using generic links to <https://rdrr.io>. | |
#' See `vignette("linking")` for more information. | |
#' * Generate a `sitemap.xml`, increasing the searchability of your site. | |
#' * Automatically generate a `CNAME` when | |
#' [deploying to github][deploy_site_github]. | |
#' | |
#' ```yaml | |
#' url: https://pkgdown.r-lib.org | |
#' ``` | |
#' | |
#' `title` overrides the default site title, which is the package name. | |
#' It's used in the page title and default navbar. | |
#' | |
#' You can also provided information to override the default display of | |
#' the authors. Provided a list named with the name of each author, | |
#' including `href` to add a link, or `html` to override the | |
#' text: | |
#' | |
#' ``` | |
#' authors: | |
#' Hadley Wickham: | |
#' href: http://hadley.nz | |
#' RStudio: | |
#' href: https://www.rstudio.com | |
#' html: <img src="https://www.tidyverse.org/rstudio-logo.svg" height="24" /> | |
#' ``` | |
#' | |
#' @section Development mode: | |
#' The development mode of a site controls four main things: | |
#' | |
#' * Where the site is built. | |
#' * The colour of the package version in the navbar. | |
#' * The optional tooltip associated with the version. | |
#' * The indexing of the site by search engines. | |
#' | |
#' There are currently three possible development modes: | |
#' | |
#' * **release**: site written to `docs/`, the version gets the default | |
#' colouring, and no message. | |
#' | |
#' * **development**: written to `docs/dev/`, the version gets a danger label, | |
#' and message stating these are docs for an in-development version of the | |
#' package. The `noindex` meta tag is used to ensure that these packages are | |
#' not indexed by search engines. | |
#' | |
#' * **unreleased**: the package is written to `docs/`, the version gets a "danger" | |
#' label, and the message indicates the package is not yet on CRAN. | |
#' | |
#' The default development mode is "release". You can override it by adding a | |
#' new `development` field to `_pkgdown.yml`, e.g. | |
#' | |
#' ``` | |
#' development: | |
#' mode: devel | |
#' ``` | |
#' | |
#' You can also have pkgdown automatically detect the mode with: | |
#' | |
#' ``` | |
#' development: | |
#' mode: auto | |
#' ``` | |
#' | |
#' The mode will be automatically determined based on the version number: | |
#' | |
#' * `0.0.0.9000` (`0.0.0.*`): unreleased | |
#' * four version components: development | |
#' * everything else -> release | |
#' | |
#' There are three other options that you can control: | |
#' | |
#' ``` | |
#' development: | |
#' destination: dev | |
#' version_label: danger | |
#' version_tooltip: "Custom message here" | |
#' ``` | |
#' | |
#' `destination` allows you to override the default subdirectory used for the | |
#' development site; it defaults to `dev/`. `version_label` allows you to | |
#' override the style used for development (and unreleased) versions of the | |
#' package. It defaults to "danger", but you can set to "default", "info", or | |
#' "warning" instead. (The precise colours are determined by your bootstrap | |
#' theme, but become progressively more eye catching as you go from default | |
#' to danger). Finally, you can choose to override the default tooltip with | |
#' `version_tooltip`. | |
#' | |
#' @section YAML config - navbar: | |
#' | |
#' By default, the top navigation bar (the "navbar") will contain links to: | |
#' | |
#' * "Get Started", if you have an article with the same name as the package | |
#' (e.g., `vignettes/pkgdown.Rmd`). | |
#' * Reference | |
#' * Articles (i.e., vignettes, if present). | |
#' * News (if present). | |
#' * A "github" icon with a link to your | |
#' github repo (if listed in the `DESCRIPTION` url field). | |
#' | |
#' You can override these defaults with the `navbar` field. It has two primary | |
#' components: `structure` and `components`. These components interact in | |
#' a somewhat complicated way, but the complexity allows you to make minor | |
#' tweaks to part of the navbar while relying on pkgdown to automatically | |
#' generate the rest. | |
#' | |
#' The `structure` defines the layout of the navbar, i.e. the order | |
#' of the components, and whether they're right aligned or left aligned. | |
#' You can use this component to change the order of the default components, | |
#' and to add your own components. | |
#' | |
#' ``` | |
#' navbar: | |
#' structure: | |
#' left: [intro, reference, articles, tutorials, news] | |
#' right: [github] | |
#' ```` | |
#' | |
#' The `components` describes the appearance of each element in the navbar. | |
#' It uses the same | |
#' syntax as [RMarkdown](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation). | |
#' The following YAML snippet illustrates some of the most important features. | |
#' | |
#' ``` | |
#' navbar: | |
#' components: | |
#' articles: | |
#' text: Articles | |
#' menu: | |
#' - text: Category A | |
#' - text: Title A1 | |
#' href: articles/a1.html | |
#' - text: Title A2 | |
#' href: articles/a2.html | |
#' - text: ------- | |
#' - text: "Category B" | |
#' - text: Title B1 | |
#' menu: | |
#' - text "Sub-category B11" | |
#' href: articles/b11.html | |
#' twitter: | |
#' icon: "fab fa-twitter fa-lg" | |
#' href: https://twitter.com/hadleywickham | |
#' ``` | |
#' | |
#' Components can contain sub-`menu`s with headings (indicated by missing | |
#' `href`) and separators (indicated by a bunch of `-`). You can also use | |
#' `icon`s from [fontawesome](https://fontawesome.com/icons?d=gallery). | |
#' | |
#' This yaml would override the default "articles" component, | |
#' and add a new "twitter" component. Unless you explicitly mention new | |
#' components in the `structure` they'll be added to the far right of the | |
#' left menu. | |
#' | |
#' @section YAML config - search: | |
#' You can use [docsearch](https://community.algolia.com/docsearch/) by algolia | |
#' to add search to your site. | |
#' | |
#' ``` | |
#' template: | |
#' params: | |
#' docsearch: | |
#' api_key: API_KEY | |
#' index_name: INDEX_NAME | |
#' ``` | |
#' | |
#' You also need to add a `url:` field, see above. | |
#' | |
#' @section YAML config - template: | |
#' You can get complete control over the appearance of the site using the | |
#' `template` component. There are two components to the template: | |
#' the HTML templates used to layout each page, and the css/js assets | |
#' used to render the page in the browser. | |
#' | |
#' The easiest way to tweak the default style is to use a bootswatch template, | |
#' by passing on the `bootswatch` template parameter to the built-in | |
#' template: | |
#' | |
#' ``` | |
#' template: | |
#' params: | |
#' bootswatch: cerulean | |
#' ``` | |
#' | |
#' See a complete list of themes and preview how they look at | |
#' <https://gallery.shinyapps.io/117-shinythemes/>: | |
#' | |
#' Optionally provide the `ganalytics` template parameter to enable | |
#' [Google Analytics](https://marketingplatform.google.com/about/analytics/). | |
#' It should correspond to your | |
#' [tracking id](https://support.google.com/analytics/answer/1008080). | |
#' | |
#' When enabling Google Analytics, be aware of the type and amount of | |
#' user information that you are collecting. You may wish to limit the | |
#' extent of data collection or to add a privacy disclosure to your | |
#' site, in keeping with current laws and regulations. | |
#' | |
#' ``` | |
#' template: | |
#' params: | |
#' ganalytics: UA-000000-01 | |
#' ``` | |
#' | |
#' Suppress indexing of your pages by web robots by setting `noindex: | |
#' true`: | |
#' | |
#' ``` | |
#' template: | |
#' params: | |
#' noindex: true | |
#' ``` | |
#' | |
#' You can also override the default templates and provide additional | |
#' assets. You can do so by either storing in a `package` with | |
#' directories `inst/pkgdown/assets` and `inst/pkgdown/templates`, | |
#' or by supplying `path` and `asset_path`. To suppress inclusion | |
#' of the default assets, set `default_assets` to false. | |
#' | |
#' ``` | |
#' template: | |
#' package: mycustompackage | |
#' | |
#' # OR: | |
#' | |
#' template: | |
#' path: path/to/templates | |
#' assets: path/to/assets | |
#' default_assets: false | |
#' ``` | |
#' | |
#' These settings are currently recommended for advanced users only. There | |
#' is little documentation, and you'll need to read the existing source | |
#' for pkgdown templates to ensure that you use the correct components. | |
#' | |
#' @section YAML config - repo: | |
#' pkgdown automatically generates links to the source repository in a few | |
#' places | |
#' | |
#' * Articles and documentation topics are linked back to the | |
#' underlying source file. | |
#' | |
#' * The NEWS automatically links issue numbers and user names. | |
#' | |
#' * The homepage provides a link to "Browse source code" | |
#' | |
#' pkgdown automatically figures out the necessary URLs if you link to a GitHub | |
#' or GitLab repo in your `BugReports` or `URL` field. Otherwise, you can | |
#' supply your own in the `repo` component: | |
#' | |
#' ```yaml | |
#' repo: | |
#' url: | |
#' home: https://github.com/r-lib/pkgdown/ | |
#' source: https://github.com/r-lib/pkgdown/blob/master/ | |
#' issue: https://github.com/r-lib/pkgdown/issues/ | |
#' user: https://github.com/ | |
#' ``` | |
#' | |
#' * `home`: path to package home on source code repository. | |
#' * `source:`: path to source of individual file in master branch. | |
#' * `issue`: path to individual issue. | |
#' * `user`: path to user. | |
#' | |
#' The varying components (e.g. path, issue number, user name) are pasted on | |
#' the end of these URLs so they should have trailing `/`s. | |
#' | |
#' pkgdown defaults to using the "master" branch for source file URLs. This can | |
#' be configured to use a specific branch when linking to source files by | |
#' specifying a branch name: | |
#' | |
#' ```yaml | |
#' repo: | |
#' branch: main | |
#' ```` | |
#' | |
#' @section YAML config - deploy: | |
#' `deploy` currently offers a single parameter: | |
#' | |
#' * `install_metadata` allows you to install package index metadata into | |
#' the package itself. Normally this metadata is made available on the | |
#' published site; installing it into your package means that it's | |
#' available for autolinking even if your website is not reachable at build | |
#' time (e.g. because it's only behind the firewall or requires auth). | |
#' | |
#' ```yaml | |
#' deploy: | |
#' install_metadata: true | |
#' ``` | |
#' | |
#' @section Options: | |
#' Users with limited internet connectivity can disable CRAN checks by setting | |
#' `options(pkgdown.internet = FALSE)`. This will also disable some features | |
#' from pkgdown that requires an internet connectivity. However, if it is used | |
#' to build docs for a package that requires internet connectivity in examples | |
#' or vignettes, this connection is required as this option won't apply on them. | |
#' | |
#' Users can set a timeout for `build_site(new_process = TRUE)` with | |
#' `options(pkgdown.timeout = Inf)`, which is useful to prevent stalled builds from | |
#' hanging in cron jobs. | |
#' | |
#' @inheritParams build_articles | |
#' @inheritParams build_reference | |
#' @param lazy If `TRUE`, will only rebuild articles and reference pages | |
#' if the source is newer than the destination. | |
#' @param devel Use development or deployment process? | |
#' | |
#' If `TRUE`, uses lighter-weight process suitable for rapid | |
#' iteration; it will run examples and vignettes in the current process, | |
#' and will load code with `pkgload::load_all()`. | |
#' | |
#' If `FALSE`, will first install the package to a temporary library, | |
#' and will run all examples and vignettes in a new process. | |
#' | |
#' `build_site()` defaults to `devel = FALSE` so that you get high fidelity | |
#' outputs when you building the complete site; `build_reference()`, | |
#' `build_home()` and friends default to `devel = TRUE` so that you can | |
#' rapidly iterate during development. | |
#' @param new_process If `TRUE`, will run `build_site()` in a separate process. | |
#' This enhances reproducibility by ensuring nothing that you have loaded | |
#' in the current process affects the build process. | |
#' @param install If `TRUE`, will install the package in a temporary library | |
#' so it is available for vignettes. | |
#' @export | |
#' @examples | |
#' \dontrun{ | |
#' build_site() | |
#' | |
#' build_site(override = list(destination = tempdir())) | |
#' } | |
build_site <- function(pkg = ".", | |
examples = TRUE, | |
run_dont_run = FALSE, | |
seed = 1014, | |
lazy = FALSE, | |
override = list(), | |
preview = NA, | |
devel = FALSE, | |
new_process = !devel, | |
install = !devel, | |
document = "DEPRECATED") { | |
pkg <- as_pkgdown(pkg, override = override) | |
if (!missing(document)) { | |
warning("`document` is deprecated. Please use `devel` instead.", call. = FALSE) | |
devel <- document | |
} | |
if (install) { | |
withr::local_temp_libpaths() | |
rule("Installing package into temporary library") | |
utils::install.packages(pkg$src_path, repos = NULL, type = "source", quiet = TRUE) | |
} | |
if (new_process) { | |
build_site_external( | |
pkg = pkg, | |
examples = examples, | |
run_dont_run = run_dont_run, | |
seed = seed, | |
lazy = lazy, | |
override = override, | |
preview = preview, | |
devel = devel | |
) | |
} else { | |
build_site_local( | |
pkg = pkg, | |
examples = examples, | |
run_dont_run = run_dont_run, | |
seed = seed, | |
lazy = lazy, | |
override = override, | |
preview = preview, | |
devel = devel | |
) | |
} | |
} | |
build_site_external <- function(pkg = ".", | |
examples = TRUE, | |
run_dont_run = FALSE, | |
seed = 1014, | |
lazy = FALSE, | |
override = list(), | |
preview = NA, | |
devel = TRUE) { | |
args <- list( | |
pkg = pkg, | |
examples = examples, | |
run_dont_run = run_dont_run, | |
seed = seed, | |
lazy = lazy, | |
override = override, | |
install = FALSE, | |
preview = FALSE, | |
new_process = FALSE, | |
devel = devel, | |
crayon_enabled = crayon::has_color(), | |
crayon_colors = crayon::num_colors(), | |
pkgdown_internet = has_internet() | |
) | |
callr::r( | |
function(..., crayon_enabled, crayon_colors, pkgdown_internet) { | |
options( | |
crayon.enabled = crayon_enabled, | |
crayon.colors = crayon_colors, | |
pkgdown.internet = pkgdown_internet | |
) | |
pkgdown::build_site(...) | |
}, | |
args = args, | |
show = TRUE, | |
timeout = getOption('pkgdown.timeout', Inf) | |
) | |
preview_site(pkg, preview = preview) | |
invisible() | |
} | |
build_site_local <- function(pkg = ".", | |
examples = TRUE, | |
run_dont_run = FALSE, | |
seed = 1014, | |
lazy = FALSE, | |
override = list(), | |
preview = NA, | |
devel = TRUE | |
) { | |
pkg <- section_init(pkg, depth = 0, override = override) | |
rule("Building pkgdown site", line = "=") | |
cat_line("Reading from: ", src_path(path_abs(pkg$src_path))) | |
cat_line("Writing to: ", dst_path(path_abs(pkg$dst_path))) | |
init_site(pkg) | |
build_home(pkg, override = override, preview = FALSE) | |
build_reference(pkg, | |
lazy = lazy, | |
examples = examples, | |
run_dont_run = run_dont_run, | |
seed = seed, | |
override = override, | |
preview = FALSE, | |
devel = devel | |
) | |
build_articles(pkg, lazy = lazy, override = override, preview = FALSE) | |
build_tutorials(pkg, override = override, preview = FALSE) | |
build_news(pkg, override = override, preview = FALSE) | |
rule("DONE", line = "=") | |
preview_site(pkg, preview = preview) | |
} |