diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index ecaf36d34..46f6c7ab2 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -1,11 +1,13 @@ -# Workflow derived from https://github.com/r-lib/actions/tree/master/examples +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help on: push: branches: [main, master] - tags: ['*'] pull_request: - branches: [master, main] + branches: [main, master] + release: + types: [published] + workflow_dispatch: name: pkgdown @@ -13,14 +15,18 @@ jobs: pkgdown: if: github.event_name == 'push' || github.event.pull_request.head.repo.fork == false runs-on: ubuntu-latest + # Only restrict concurrency for non-PR jobs + concurrency: + group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} - isPush: ${{ github.event_name == 'push' }} - + isPush: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }} + permissions: + contents: write steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: r-lib/actions/setup-tinytex@v2 diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 7a69ec410..4b5b0eb68 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -33,7 +33,7 @@ jobs: covr::codecov( quiet = FALSE, clean = FALSE, - install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package") + install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package") ) shell: Rscript {0} diff --git a/DESCRIPTION b/DESCRIPTION index 417184f65..e9ceca965 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,13 +2,13 @@ Package: pkgdown Title: Make Static HTML Documentation for a Package Version: 2.0.7.9000 Authors@R: c( - person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), + person("Hadley", "Wickham", , "hadley@posit.co", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-4757-117X")), person("Jay", "Hesselberth", role = "aut", comment = c(ORCID = "0000-0002-6299-179X")), person("Maëlle", "Salmon", role = "aut", comment = c(ORCID = "0000-0002-2815-0399")), - person("RStudio", role = c("cph", "fnd")) + person("Posit Software, PBC", role = c("cph", "fnd")) ) Description: Generate an attractive and useful website from a source package. 'pkgdown' converts your documentation, vignettes, 'README', @@ -18,7 +18,7 @@ License: MIT + file LICENSE URL: https://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown BugReports: https://github.com/r-lib/pkgdown/issues Depends: - R (>= 3.1.0) + R (>= 3.6) Imports: bslib (>= 0.3.1), callr (>= 3.7.3), @@ -44,6 +44,7 @@ Suggests: covr, diffviewer, evaluate, + gert, htmltools, htmlwidgets, knitr, @@ -66,5 +67,5 @@ Remotes: rstudio/bslib Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.2.9000 +RoxygenNote: 7.2.3 SystemRequirements: pandoc diff --git a/LICENSE b/LICENSE index 8b3f0d421..7acb56cd7 100644 --- a/LICENSE +++ b/LICENSE @@ -1,2 +1,2 @@ -YEAR: 2014--2018 -COPYRIGHT HOLDER: RStudio +YEAR: 2023 +COPYRIGHT HOLDER: pkgdown authors diff --git a/LICENSE.md b/LICENSE.md index c9f975512..0a6c13c63 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ # MIT License -Copyright (c) 2014-2018 RStudio +Copyright (c) 2023 pkgdown authors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/NEWS.md b/NEWS.md index 3714542c3..f353ab075 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,8 +1,11 @@ # pkgdown (development version) +* Preserve Markdown code blocks with class rmd from roxygen2 docs (@salim-b, #2298). * Avoid unwanted linebreaks from parsing `DESCRIPTION` (@salim-b, #2247). * Remove redundant entries in the documentation index when multiple explicit `@usage` tags are provided (@klmr, #2302) * The article index now sorts vignettes and non-vignette articles alphabetically by their filename (literally, their `basename()`), by default (@jennybc, #2253). +* Add Catalan translation (@jmaspons, #2333) +* Set RNG seed for htmlwidgets IDs. This reduces noise in pkgdown reference HTML output when examples generate htmlwidgets (@salim-b, #2294). # pkgdown 2.0.7 diff --git a/R/build-github.R b/R/build-github.R index 6f4a40c34..1aff9055a 100644 --- a/R/build-github.R +++ b/R/build-github.R @@ -8,7 +8,7 @@ #' #' It is designed to be run in CI, so by default it: #' -#' * Clean out the old site. +#' * Cleans out the old site. #' * Does not install the package. #' * Runs [build_site()] in process. #' diff --git a/R/build-reference.R b/R/build-reference.R index ef8c94e53..add462c13 100644 --- a/R/build-reference.R +++ b/R/build-reference.R @@ -139,8 +139,8 @@ #' rapidly prototype. It is set to `FALSE` by [build_site()]. #' @param run_dont_run Run examples that are surrounded in \\dontrun? #' @param examples Run examples? -#' @param seed Seed used to initialize so that random examples are -#' reproducible. +#' @param seed Seed used to initialize random number generation so that +#' examples are reproducible. #' @param devel Determines how code is loaded in order to run examples. #' If `TRUE` (the default), assumes you are in a live development #' environment, and loads source package with [pkgload::load_all()]. @@ -223,6 +223,9 @@ examples_env <- function(pkg, seed = 1014, devel = TRUE, envir = parent.frame()) width <- purrr::pluck(pkg, "meta", "code", "width", .default = 80) withr::local_options(width = width, .local_envir = envir) withr::local_seed(seed) + if (requireNamespace("htmlwidgets", quietly = TRUE)) { + htmlwidgets::setWidgetIdSeed(seed) + } examples_env <- child_env(globalenv()) if (file_exists(pre_path)) { diff --git a/R/build.R b/R/build.R index e7ccef797..a44a0a99a 100644 --- a/R/build.R +++ b/R/build.R @@ -122,20 +122,16 @@ #' to danger). Finally, you can choose to override the default tooltip with #' `version_tooltip`. #' -#' @section Navigation bar: -#' ```{r child="man/rmd-fragments/navbar-configuration.Rmd"} -#' ``` -#' -#' You can also customise the colour scheme of the navbar by using the `type` -#' and `bg` parameters. See `vignette("customise")` for more details. +#' ## Page layout #' -#' @section Footer: -#' ```{r child="man/rmd-fragments/footer-configuration.Rmd"} -#' ``` +#' The `navbar`, `footer`, and `sidebar` fields control the appearance +#' of the navbar, footer, and sidebar respectively. They have many individual +#' options which are documented in the **Layout** section of +#' `vignette("customise")`. #' #' @section Search: -#' The `search` field controls the built-in search. See `vignette("search")` -#' for details. +#' The `search` field controls the built-in search and is +#' documented in `vignette("search")`. #' #' @section Template: #' The `template` field is mostly used to control the appearance of the site. diff --git a/R/tweak-reference.R b/R/tweak-reference.R index 5acac5866..803db0aa8 100644 --- a/R/tweak-reference.R +++ b/R/tweak-reference.R @@ -61,6 +61,8 @@ tweak_highlight_other <- function(div) { lang <- sub("sourceCode ", "", xml2::xml_attr(div, "class")) # since roxygen 7.2.0 generic code blocks have sourceCode with no lang if (!is.na(lang) && lang == "sourceCode") lang <- "r" + # Pandoc does not recognize rmd as a language :-) + if (tolower(lang) %in% c("rmd", "qmd")) lang <- "markdown" # many backticks to account for possible nested code blocks # like a Markdown code block with code chunks inside md <- paste0("``````", lang, "\n", xml2::xml_text(code), "\n``````") diff --git a/README.Rmd b/README.Rmd index 86b307798..9211af9c8 100644 --- a/README.Rmd +++ b/README.Rmd @@ -34,7 +34,8 @@ install.packages("pkgdown") ::: .pkgdown-devel ```{r, eval = FALSE} # Install development version from GitHub -devtools::install_github("r-lib/pkgdown") +# install.packages("pak") +pak::pak("r-lib/pkgdown") ``` ::: diff --git a/README.md b/README.md index 77fec024f..8f6acb661 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,8 @@ install.packages("pkgdown") ``` r # Install development version from GitHub -devtools::install_github("r-lib/pkgdown") +# install.packages("pak") +pak::pak("r-lib/pkgdown") ``` @@ -81,7 +82,7 @@ Then learn about the many new ways to customise your site in ## In the wild -At last count, pkgdown is used [by over 6,000 +At last count, pkgdown is used [by over 8,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: diff --git a/inst/po/ca/LC_MESSAGES/R-pkgdown.mo b/inst/po/ca/LC_MESSAGES/R-pkgdown.mo new file mode 100644 index 000000000..04d6d18d8 Binary files /dev/null and b/inst/po/ca/LC_MESSAGES/R-pkgdown.mo differ diff --git a/man/build_home.Rd b/man/build_home.Rd index 68ac25b88..6cf9da56f 100644 --- a/man/build_home.Rd +++ b/man/build_home.Rd @@ -185,12 +185,14 @@ and can contain \code{href} and/or \code{html} fields: \item If \code{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 skip over it. } \if{html}{\out{
}}\preformatted{authors: firstname lastname: href: "http://name-website.com" - html: "" + html: "" }\if{html}{\out{
}} By default, the "developers" list shown in the sidebar and footer is populated by the maintainer ("cre"), authors diff --git a/man/build_reference.Rd b/man/build_reference.Rd index 81561844a..730c2e2a3 100644 --- a/man/build_reference.Rd +++ b/man/build_reference.Rd @@ -31,8 +31,8 @@ rapidly prototype. It is set to \code{FALSE} by \code{\link[=build_site]{build_s \item{run_dont_run}{Run examples that are surrounded in \\dontrun?} -\item{seed}{Seed used to initialize so that random examples are -reproducible.} +\item{seed}{Seed used to initialize random number generation so that +examples are reproducible.} \item{override}{An optional named list used to temporarily override values in \verb{_pkgdown.yml}} diff --git a/man/build_site.Rd b/man/build_site.Rd index cb56aedb0..60ab07f0f 100644 --- a/man/build_site.Rd +++ b/man/build_site.Rd @@ -25,8 +25,8 @@ build_site( \item{run_dont_run}{Run examples that are surrounded in \\dontrun?} -\item{seed}{Seed used to initialize so that random examples are -reproducible.} +\item{seed}{Seed used to initialize random number generation so that +examples are reproducible.} \item{lazy}{If \code{TRUE}, will only rebuild articles and reference pages if the source is newer than the destination.} @@ -181,138 +181,20 @@ theme, but become progressively more eye catching as you go from default to danger). Finally, you can choose to override the default tooltip with \code{version_tooltip}. } -} - -\section{Navigation bar}{ - -You can customise the navigation bar that appears at the top of the page with the \code{navbar} field. -It's made up of two pieces: \code{structure}, which defines the overall layout, and \code{components}, which defines what each piece looks like. -This organisation makes it easy to mix and match pkgdown defaults with your own customisations. - -This is the default structure: - -\if{html}{\out{
}}\preformatted{navbar: - structure: - left: [intro, reference, articles, tutorials, news] - right: [search, github] -}\if{html}{\out{
}} - -It makes use of the the six built-in components: -\itemize{ -\item \code{intro}: "Get Started", which links to a vignette with the same name as the package. -\item \code{reference}, if there are any \code{.Rd} files. -\item \code{articles}, if there are any vignettes or articles. -\item \code{tutorials}, if there any tutorials. -\item \code{news}, if \code{NEWS.md} exists. -\item \code{search}, the search box (see \code{vignette("search")} for more details). -\item \code{github}, a link to the source repository (with an icon), if it can be automatically determined from the \code{DESCRIPTION}. -} - -You can use the \code{structure} field to reorganise the navbar without changing the default contents: - -\if{html}{\out{
}}\preformatted{navbar: - structure: - left: [search] - right: [reference, articles] -}\if{html}{\out{
}} - -You can use \code{components} to override the default content. -For example, this yaml provides a custom articles menu: - -\if{html}{\out{
}}\preformatted{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: Article B1 - href: articles/b1.html -}\if{html}{\out{
}} - -Components uses the same syntax as \href{https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation}{RMarkdown menus}. -The elements of \code{menu} can be: -\itemize{ -\item A link (\code{text} + \code{href}) -\item A heading (just \code{text}) -\item A separator (\verb{text: ——–}) -} - -Instead of text, you can also use the name of an \code{icon}s from \href{https://fontawesome.com/icons?d=gallery}{fontawesome}. -You should also provide a textual description in the \code{aria-label} field for screenreader users. - -To add a new component to the navbar, you need to modify both \code{structure} and \code{components}. -For example, the following yaml adds a new "twitter" component that appears to the left of the github icon. -\if{html}{\out{
}}\preformatted{navbar: - structure: - right: [twitter, github] - components: - twitter: - icon: fa-twitter - href: http://twitter.com/hadleywickham - aria-label: Twitter -}\if{html}{\out{
}} - -Finally, you can add arbitrary HTML to three locations in the navbar: - -\if{html}{\out{
}}\preformatted{template: - includes: - before_title: - after_navbar: -}\if{html}{\out{
}} - -These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down. +\subsection{Page layout}{ -You can also customise the colour scheme of the navbar by using the \code{type} -and \code{bg} parameters. See \code{vignette("customise")} for more details. +The \code{navbar}, \code{footer}, and \code{sidebar} fields control the appearance +of the navbar, footer, and sidebar respectively. They have many individual +options which are documented in the \strong{Layout} section of +\code{vignette("customise")}. } - -\section{Footer}{ - -You can customise the footer with the \code{footer} field. -It's made up of two pieces: \code{structure}, which defines the overall layout, and \code{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: - -\if{html}{\out{
}}\preformatted{footer: - structure: - left: developed_by - right: built_with -}\if{html}{\out{
}} - -Which uses two of the three built-in components: -\itemize{ -\item \code{developed_by}, a sentence describing the main authors of the package. (See \code{?build_home} if you want to tweak \emph{which} authors appear in the footer.) -\item \code{built_with}, a sentence advertising pkgdown. -\item \code{package}, the name of the package. -} - -You can override these defaults with the \code{footer} field. -The example below puts the authors' information on the right along with a legal disclaimer, and puts the pkgdown link on the left. - -\if{html}{\out{
}}\preformatted{footer: - structure: - left: pkgdown - right: [authors, legal] - components: - legal: Provided without **any warranty**. -}\if{html}{\out{
}} - -Each side is pasted into a single string (separated by \code{" "}) and then converted from markdown to HTML. } \section{Search}{ -The \code{search} field controls the built-in search. See \code{vignette("search")} -for details. +The \code{search} field controls the built-in search and is +documented in \code{vignette("search")}. } \section{Template}{ diff --git a/man/build_site_github_pages.Rd b/man/build_site_github_pages.Rd index 181df1227..c4cce889f 100644 --- a/man/build_site_github_pages.Rd +++ b/man/build_site_github_pages.Rd @@ -37,7 +37,7 @@ file if needed. It is designed to be run in CI, so by default it: \itemize{ -\item Clean out the old site. +\item Cleans out the old site. \item Does not install the package. \item Runs \code{\link[=build_site]{build_site()}} in process. } diff --git a/man/figures/logo.png b/man/figures/logo.png index 8b92dae7d..c415dc0ea 100644 Binary files a/man/figures/logo.png and b/man/figures/logo.png differ diff --git a/man/pkgdown-package.Rd b/man/pkgdown-package.Rd index 9fb5fa1f4..0a833e0db 100644 --- a/man/pkgdown-package.Rd +++ b/man/pkgdown-package.Rd @@ -20,7 +20,7 @@ Useful links: } \author{ -\strong{Maintainer}: Hadley Wickham \email{hadley@rstudio.com} (\href{https://orcid.org/0000-0003-4757-117X}{ORCID}) +\strong{Maintainer}: Hadley Wickham \email{hadley@posit.co} (\href{https://orcid.org/0000-0003-4757-117X}{ORCID}) Authors: \itemize{ @@ -30,7 +30,7 @@ Authors: Other contributors: \itemize{ - \item RStudio [copyright holder, funder] + \item Posit Software, PBC [copyright holder, funder] } } diff --git a/man/rmd-fragments/authors-configuration.Rmd b/man/rmd-fragments/authors-configuration.Rmd index 877d97090..5b45a382f 100644 --- a/man/rmd-fragments/authors-configuration.Rmd +++ b/man/rmd-fragments/authors-configuration.Rmd @@ -58,12 +58,14 @@ and can contain `href` and/or `html` fields: * 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 skip over it. ```yaml authors: firstname lastname: href: "http://name-website.com" - html: "" + html: "" ``` diff --git a/man/rmd-fragments/navbar-configuration.Rmd b/man/rmd-fragments/navbar-configuration.Rmd index 9940e8b35..69c3547b3 100644 --- a/man/rmd-fragments/navbar-configuration.Rmd +++ b/man/rmd-fragments/navbar-configuration.Rmd @@ -13,7 +13,7 @@ navbar: It makes use of the the six built-in components: -- `intro`: "Get Started", which links to a vignette with the same name as the package. +- `intro`: "Get Started", which links to a vignette with the same name as the package[^dots]. - `reference`, if there are any `.Rd` files. - `articles`, if there are any vignettes or articles. - `tutorials`, if there any tutorials. @@ -21,6 +21,9 @@ It makes use of the the six built-in components: - `search`, the search box (see `vignette("search")` for more details). - `github`, a link to the source repository (with an icon), if it can be automatically determined from the `DESCRIPTION`. +[^dots]: Note that dots (`.`) in the package name need to be replaced by hyphens (`-`) in the vignette filename to be recognized as the intro. That means for a + package `foo.bar` the intro needs to be named `foo-bar.Rmd`. + You can use the `structure` field to reorganise the navbar without changing the default contents: ``` yaml @@ -87,3 +90,5 @@ template: ``` These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down. + +You can also customise the colour scheme of the navbar by using the `type` and `bg` parameters. See above for details. diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index cfd6356d8..8fbd7c85e 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -10,9 +10,10 @@ authors: href: https://masalmon.eu Hadley Wickham: href: http://hadley.nz - RStudio: - href: https://www.rstudio.com - html: RStudio + Posit Software, PBC: + href: https://www.posit.co + html: >- + Posit template: bootstrap: 5 diff --git a/pkgdown/favicon/apple-touch-icon-120x120.png b/pkgdown/favicon/apple-touch-icon-120x120.png index 3d77ee5f0..9386a565a 100644 Binary files a/pkgdown/favicon/apple-touch-icon-120x120.png and b/pkgdown/favicon/apple-touch-icon-120x120.png differ diff --git a/pkgdown/favicon/apple-touch-icon-152x152.png b/pkgdown/favicon/apple-touch-icon-152x152.png index e10c0ddba..7c41c0738 100644 Binary files a/pkgdown/favicon/apple-touch-icon-152x152.png and b/pkgdown/favicon/apple-touch-icon-152x152.png differ diff --git a/pkgdown/favicon/apple-touch-icon-180x180.png b/pkgdown/favicon/apple-touch-icon-180x180.png index cea144241..4d75fa735 100644 Binary files a/pkgdown/favicon/apple-touch-icon-180x180.png and b/pkgdown/favicon/apple-touch-icon-180x180.png differ diff --git a/pkgdown/favicon/apple-touch-icon-60x60.png b/pkgdown/favicon/apple-touch-icon-60x60.png index 679f010e8..18049b161 100644 Binary files a/pkgdown/favicon/apple-touch-icon-60x60.png and b/pkgdown/favicon/apple-touch-icon-60x60.png differ diff --git a/pkgdown/favicon/apple-touch-icon-76x76.png b/pkgdown/favicon/apple-touch-icon-76x76.png index 884b4d497..755d5f03e 100644 Binary files a/pkgdown/favicon/apple-touch-icon-76x76.png and b/pkgdown/favicon/apple-touch-icon-76x76.png differ diff --git a/pkgdown/favicon/apple-touch-icon.png b/pkgdown/favicon/apple-touch-icon.png index 0b2624a1d..f1d46ea80 100644 Binary files a/pkgdown/favicon/apple-touch-icon.png and b/pkgdown/favicon/apple-touch-icon.png differ diff --git a/pkgdown/favicon/favicon-16x16.png b/pkgdown/favicon/favicon-16x16.png index 25bea8c83..58c7cba9a 100644 Binary files a/pkgdown/favicon/favicon-16x16.png and b/pkgdown/favicon/favicon-16x16.png differ diff --git a/pkgdown/favicon/favicon-32x32.png b/pkgdown/favicon/favicon-32x32.png index 138246197..94135aae8 100644 Binary files a/pkgdown/favicon/favicon-32x32.png and b/pkgdown/favicon/favicon-32x32.png differ diff --git a/pkgdown/favicon/favicon.ico b/pkgdown/favicon/favicon.ico index 8e9b72f45..7fef537c9 100644 Binary files a/pkgdown/favicon/favicon.ico and b/pkgdown/favicon/favicon.ico differ diff --git a/po/R-ca.po b/po/R-ca.po new file mode 100644 index 000000000..926030691 --- /dev/null +++ b/po/R-ca.po @@ -0,0 +1,293 @@ +msgid "" +msgstr "" +"Project-Id-Version: pkgdown 2.0.6.9000\n" +"POT-Creation-Date: 2022-11-25 22:59+0100\n" +"PO-Revision-Date: 2023-08-16 00:23+0200\n" +"Last-Translator: jmaspons \n" +"Language: ca\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Lokalize 23.04.3\n" + +#: build-404.R:11 +msgid "Page not found (404)" +msgstr "No s'ha trobat la pàgina (404)" + +#: build-404.R:12 +msgid "Content not found. Please use links in the navbar." +msgstr "" +"No s'ha trobat el contingut. Useu els enllaços de la barra de navegació." + +#: build-articles.R:381 navbar.R:136 navbar.R:143 navbar.R:158 +msgid "Articles" +msgstr "Articles" + +#: build-articles.R:430 +msgid "All vignettes" +msgstr "Totes les vinyetes" + +#: build-footer.R:23 +msgid "Developed by" +msgstr "Desenvolupat per" + +#: build-footer.R:28 +msgid "Site built with pkgdown %s." +msgstr "Lloc construït amb pkgdown %s." + +#: build-home-authors.R:69 +msgid "More about authors..." +msgstr "Més sobre els autors..." + +#: build-home-authors.R:72 +msgid "Developers" +msgstr "Desenvolupadors" + +#: build-home-authors.R:77 render.R:96 +msgid "Authors" +msgstr "Autors" + +#: build-home-authors.R:169 +msgid "author" +msgstr "autor" + +#: build-home-authors.R:170 +msgid "compiler" +msgstr "compilador" + +#: build-home-authors.R:171 +msgid "contractor" +msgstr "contractista" + +#: build-home-authors.R:172 +msgid "contributor" +msgstr "col·laborador" + +#: build-home-authors.R:173 +msgid "copyright holder" +msgstr "titular dels drets d'autor" + +#: build-home-authors.R:174 +msgid "maintainer" +msgstr "mantenidor" + +#: build-home-authors.R:175 +msgid "data contributor" +msgstr "col·laborador de dades" + +#: build-home-authors.R:176 +msgid "funder" +msgstr "finançador" + +#: build-home-authors.R:177 +msgid "reviewer" +msgstr "revisor" + +#: build-home-authors.R:178 +msgid "thesis advisor" +msgstr "supervisor de tesi" + +#: build-home-authors.R:179 +msgid "translator" +msgstr "traductor" + +#: build-home-citation.R:36 +msgid "Citing %s" +msgstr "Citant %s" + +#: build-home-citation.R:91 +msgid "Authors and Citation" +msgstr "Autors i citació" + +#: build-home-community.R:23 +msgid "Contributing guide" +msgstr "Guia per contribuir" + +#: build-home-community.R:27 +msgid "Code of conduct" +msgstr "Codi de conducta" + +#: build-home-community.R:31 +msgid "Getting help" +msgstr "Obtenció d'ajuda" + +#: build-home-community.R:38 +msgid "Community" +msgstr "Comunitat" + +#: build-home-index.R:88 +msgid "Dev Status" +msgstr "Estat de desenvolupament" + +#: build-home-index.R:154 +msgid "View on %s" +msgstr "Mostra a %s" + +#: build-home-index.R:155 +msgid "Browse source code" +msgstr "Navega pel codi font" + +#: build-home-index.R:156 +msgid "Report a bug" +msgstr "Informa d'un error" + +#: build-home-index.R:160 +msgid "Links" +msgstr "Enllaços" + +#: build-home-index.R:165 +msgid "Table of contents" +msgstr "Taula de continguts" + +#: build-home-license.R:12 build-home-license.R:34 +msgid "License" +msgstr "Llicència" + +#: build-home-license.R:29 +msgid "Full license" +msgstr "Llicència completa" + +#: build-news.R:101 build-news.R:246 build-news.R:251 +msgid "Changelog" +msgstr "Registre de canvis" + +#: build-news.R:126 +msgid "Version %s" +msgstr "Versió %s" + +#: build-news.R:138 build-news.R:240 +msgid "News" +msgstr "Novetats" + +#: build-news.R:242 +msgid "Releases" +msgstr "Versions" + +#: build-news.R:298 +msgid "CRAN release: %s" +msgstr "Versió del CRAN: %s" + +#: build-reference-index.R:20 +msgid "Function reference" +msgstr "Llistat de funcions" + +#: build-reference-index.R:130 +msgid "All functions" +msgstr "Totes les funcions" + +#: build-reference.R:353 +msgid "Usage" +msgstr "Ús" + +#: build-tutorials.R:46 navbar.R:102 +msgid "Tutorials" +msgstr "Guies d'aprenentatge" + +#: development.R:72 +msgid "Released version" +msgstr "Versió publicada" + +#: development.R:73 +msgid "In-development version" +msgstr "Versió en desenvolupament" + +#: development.R:74 +msgid "Unreleased version" +msgstr "Versió no publicada" + +#: navbar.R:99 +msgid "Reference" +msgstr "Referència" + +#: navbar.R:130 +msgid "Get started" +msgstr "Comenceu" + +#: navbar.R:156 +msgid "More articles..." +msgstr "Més articles..." + +#: rd-data.R:33 +msgid "Details" +msgstr "Detalls" + +#: rd-data.R:37 +msgid "Description" +msgstr "Descripció" + +#: rd-data.R:41 +msgid "References" +msgstr "Referències" + +#: rd-data.R:45 render.R:94 +msgid "Source" +msgstr "Font" + +#: rd-data.R:49 +msgid "Format" +msgstr "Format" + +#: rd-data.R:53 +msgid "Note" +msgstr "Nota" + +#: rd-data.R:57 +msgid "Author" +msgstr "Autor" + +#: rd-data.R:61 +msgid "See also" +msgstr "Vegeu també" + +#: rd-data.R:77 +msgid "Arguments" +msgstr "Paràmetres" + +#: rd-data.R:85 +msgid "Value" +msgstr "Valor" + +#: rd-html.R:208 +msgid "# %s method for %s" +msgstr "# Mètode %s per a %s" + +#: render.R:90 +msgid "Skip to contents" +msgstr "Salta als continguts" + +#: render.R:91 +msgid "Toggle navigation" +msgstr "Commuta la navegació" + +#: render.R:92 +msgid "Search for" +msgstr "Cerca" + +#: render.R:93 +msgid "On this page" +msgstr "En aquesta pàgina" + +#: render.R:95 +msgid "Abstract" +msgstr "Resum" + +#: render.R:97 +msgid "Version" +msgstr "Versió" + +#: render.R:98 +msgid "Examples" +msgstr "Exemples" + +#: render.R:99 +msgid "Citation" +msgstr "Citació" + +#: repo.R:33 +msgid "Source:" +msgstr "Font:" + +#: tweak-homepage.R:60 +msgid "Dev status" +msgstr "Estat de desenvolupament" diff --git a/tests/testthat/_snaps/build-reference-index.md b/tests/testthat/_snaps/build-reference-index.md index 4a12ce4e3..d595dc877 100644 --- a/tests/testthat/_snaps/build-reference-index.md +++ b/tests/testthat/_snaps/build-reference-index.md @@ -123,7 +123,7 @@ - is_installed() - check_installed() icon: ~ - - path: https://rstudio.github.io/bslib/reference/bs_bundle.html + - path: https://rdrr.io/pkg/bslib/man/bs_bundle.html title: Add low-level theming customizations (from bslib) aliases: - bs_add_variables() diff --git a/tests/testthat/test-tweak-reference.R b/tests/testthat/test-tweak-reference.R index 71ab71e32..0f7ca3bf8 100644 --- a/tests/testthat/test-tweak-reference.R +++ b/tests/testthat/test-tweak-reference.R @@ -112,6 +112,14 @@ test_that("can highlight other languages", { expect_equal(xpath_text(html, "//code//span[not(span)]")[[1]], "field") }) +test_that("can highlight 'rmd'", { + skip_if_no_pandoc("2.16") + html <- xml2::read_xml('
field: value
') + tweak_highlight_other(html) + + expect_equal(xpath_attr(html, "//code//span[not(span)]", "class")[[1]], "an") +}) + test_that("fails cleanly", { html <- xml2::read_xml('
') tweak_highlight_other(html) diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index 53ea64011..c192bb50e 100644 --- a/vignettes/customise.Rmd +++ b/vignettes/customise.Rmd @@ -162,7 +162,7 @@ Because the navbar is styled with HTML, you'll need to `build_home_index(); init You can customise the contents of the navbar, footer, and home page sidebar using the `navbar`, `footer`, and `sidebar` fields. They all use a similar structure that separately defines the overall `structure` and the individual `components`. -### Navbar +### Navbar {#navbar-heading} ```{r child="../man/rmd-fragments/navbar-configuration.Rmd"} ``` diff --git a/vignettes/how-to-update-released-site.Rmd b/vignettes/how-to-update-released-site.Rmd index 48e9a3656..9ee850556 100644 --- a/vignettes/how-to-update-released-site.Rmd +++ b/vignettes/how-to-update-released-site.Rmd @@ -10,68 +10,95 @@ vignette: > ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, - comment = "#>" + comment = "#>", + eval = FALSE ) ``` -## Checklist +This vignette shows you how to update the released version of your site to match the dev version of the site, so the first step is to ensure that the dev site looks the way that you want it. -If you're already up-to-speed, here's the checklist: +## Process -* Make sure your dev site looks the way you want before embarking on an update - of your released site. Here are good instructions for updating an existing - site for pkgdown 2.0.0, Bootstrap 5, and "tidyverse/tidytemplate" (only - applies to certain packages): - -* Make sure you are using automatic development mode. In `_pkgdown.yml`: +If you're up to speed with the basic idea and just want some code to follow here it us. +Otherwise, read more below. - ``` yaml - development: - mode: auto - ``` -* Push/pull to sync your default branch. -* Create and checkout a branch based on the tag of your most recent GitHub/CRAN - release. - - Example for readr, whose latest release is 2.1.1: - `git checkout -b update-pkgdown-2-1-1 v2.1.1` - - General pattern: - `git checkout -b NEW-BRANCH-NAME NAME-OF-RELEASE-TAG` -* Backport innovations from the future. Example of a useful opening move: - `git checkout main -- _pkgdown.yml .github/workflows/pkgdown.yaml` - - Most likely candidates: - - `_pkgdown.yml` - - `.github/workflows/pkgdown.yaml` - - `Config/Needs/website: tidyverse/tidytemplate` in DESCRIPTION - - Any fixes to `README.Rmd` / `README.md` or released roxygen comments. Don't - forget to `devtools::build_readme()` or `devtools::document()`, in that - case. - - These are the two main Git commands you'll need: - ``` - git checkout REF -- path/to/a/specific/file - git cherry-pick SHA - ``` -* Monitor your progress locally with `pkgdown::build_site()`. -* Push this branch, maybe using `usethis::pr_push()`. Don't bother opening - a pull request (the branch will still be created and pushed). -* Go to your package's GHA page, maybe using `usethis::browse_github_actions()`. - Select the pkgdown workflow. Click *Run workflow* and select the branch you - just pushed. If there's no dropdown menu for this, that means your pkgdown - workflow config is not current. -* Scrutinize your newly published **released** site and make sure things look - right. -* You can let this branch sit around for a while, in case you need to iterate - on this or if you'd like to backport more niceties before your next CRAN - release. Or you can delete immediately, if you're happy with the released - site. +### Setup + +First, make sure you're in the `main` branch, and you have the latest version: + +```{r} +gert::git_branch_checkout("main") +gert::git_pull() +``` + +Next figure out the released version that we're updating: + +```{r} +ver <- desc::desc_get_version()[1, 1:3] +``` + +We'll use this to create and checkout the branch that you'll work in: + +```{r} +gert::git_branch_create(paste0("pkgdown-v", ver), paste0("v", ver)) +``` + +### Backport changes + +Now you need to backport changes from the dev site into this branch. +Run this R code to generate the git code to pull changes for the most common locations: + +```{r} +files <- c( + # overall site config + "_pkgdown.yml", + # the workflow that builds the site + ".github/workflows/pkgdown.yaml", + # readme and vignettes + "README.md", "vignettes", + # logo and favicon + "man/figures/", "pkgdown/", + # Author metadata and Config/Needs/Website + "DESCRIPTION" +) + +glue::glue("git checkout v{ver} -- {files}") +``` + +If you backport `DESCRIPTION`, you'll also need undo the change to the `Version`: + +```{r} +desc::desc_set_version(ver) +``` + +Now build the site locally and check that it looks as you expect: + +```{r} +pkgdown::build_site() +``` + +### Publish + +Now you need to publish the site. +First push your branch to GitHub: + +```{r} +usethis:::git_push_first() +``` + +Then trigger the pkgdown workflow: + +1. Go to your package's GHA page, e.g. with `usethis::browse_github_actions())`. +2. Select the pkgdown workflow. +3. Click *Run workflow* and select the branch you just pushed. + +If there's no dropdown menu for this, that means your pkgdown workflow config is not current. ## Context Before we talk about **how** to update a released site, we first establish **why** you might need to do this. -What is a released site? What other kind of pkgdown site could you have? +What is a released site? +What other kind of pkgdown site could you have? Why does updating a released site take special effort? ### Automatic development mode @@ -91,7 +118,7 @@ This directs pkgdown to "generate different sites for the development and releas The readr package demonstrates what happens in automatic development mode: -[readr.tidyverse.org](https://readr.tidyverse.org) documents the released version, i.e. what `install.packages()` would deliver. +[readr.tidyverse.org](https://readr.tidyverse.org) documents the released version, i.e. what `install.packages()` would deliver.\ [readr.tidyverse.org/dev/](https://readr.tidyverse.org/dev/) documents the dev version, i.e. what you'd get by installing from GitHub. In this mode, `pkgdown::build_site()`, consults DESCRIPTION to learn the package's version number. @@ -108,7 +135,7 @@ Now that we've established the meaning of a released (vs dev) site, we have to c Many people use `usethis::use_pkgdown_github_pages()` to do basic pkgdown setup and configure a GitHub Actions (GHA) workflow to automatically render and publish the site to GitHub Pages. Here's an overview of what this function does: -``` +``` usethis::use_pkgdown_github_pages() = use_pkgdown() + use_github_pages() + @@ -148,37 +175,36 @@ on: ``` -We build and deploy for pushes to `main` (or `master`). -We build for pull requests against `main` (or `master`). +We build and deploy for pushes to `main` (or `master`).\ +We build for pull requests against `main` (or `master`).\ But we don't deploy for pull requests. -We build and deploy when we publish a GitHub release. -By convention, we assume that a GitHub release coincides with a CRAN release. -**This is the primary mechanism for building the released pkgdown site.** +We build and deploy when we publish a GitHub release.\ +By convention, we assume that a GitHub release coincides with a CRAN release.\ +**This is the primary mechanism for building the released pkgdown site.** `pkgdown::build_site_github_pages()` consults the version in DESCRIPTION to detect whether it's building from a released version or a dev version. That determines the `dest_dir`, e.g. `docs/` for released and `docs/dev/` for dev. -For a package in automatic development mode, this means that almost all of your pushes trigger an update to the dev site. +For a package in automatic development mode, this means that almost all of your pushes trigger an update to the dev site. The released site is only updated when you push a state with a non-development version number or when you publish a GitHub release. So how do you tweak things about the released site *in between* releases? -That brings us to `workflow_dispatch:`. (Yes that dangling colon is correct.) +That brings us to `workflow_dispatch:`. +(Yes that dangling colon is correct.) -The inclusion of `workflow_dispatch` as a trigger means the pkgdown workflow can be run on demand, either manually from the browser or via the GitHub REST API. -We're going to show how to update a released site from a GitHub branch or tag, using the browser method. +The inclusion of `workflow_dispatch` as a trigger means the pkgdown workflow can be run on demand, either manually from the browser or via the GitHub REST API. We're going to show how to update a released site from a GitHub branch or tag, using the browser method. In the future, we might build some tooling around the API method. Places to learn more about triggering GHA workflows: -* -* -* +- +- +- -Before we move on, I repeat: +Before we move on, I repeat: It is important that your `main` branch have the latest pkgdown workflow. -(Or whatever your default branch is called.) -At the time of writing, this means the `v2` tag in `r-lib/actions`. +(Or whatever your default branch is called.) At the time of writing, this means the `v2` tag in `r-lib/actions`. The easiest way to get this is to install dev usethis and run `usethis::use_github_action("pkgdown")`. ## Construct a branch for the update @@ -186,19 +212,19 @@ The easiest way to get this is to install dev usethis and run `usethis::use_gith The overall goal is to create a package state from which to update the released site that corresponds to (HEAD of) a Git branch. This package state should: -* Be based on the most recent GitHub and CRAN release. -* Incorporate all desired updates to your documentation, such as pkgdown config. +- Be based on the most recent GitHub and CRAN release. +- Incorporate all desired updates to your documentation, such as pkgdown config. Create and checkout a branch based on the tag of the most recent CRAN release. For example, if readr's latest release is 2.1.1: -``` +``` git checkout -b update-pkgdown-2-1-1 v2.1.1 ``` And here is the general pattern: -``` +``` git checkout -b NEW-BRANCH-NAME NAME-OF-RELEASE-TAG ``` @@ -206,38 +232,35 @@ Now you should backport innovations from the future that you would like to retro Files you must update: -* `.github/workflows/pkgdown.yaml` -* `_pkgdown.yml` -* `Config/Needs/website` field of DESCRIPTION (And, probably, only this field! - In particular, do not mess with the version number.) +- `.github/workflows/pkgdown.yaml` +- `_pkgdown.yml` +- `Config/Needs/website` field of DESCRIPTION (And, probably, only this field! In particular, do not mess with the version number.) -Other likely candidates: +Other likely candidates: -* `README.Rmd` + `README.md`, e.g., if you've updated badges. -* Any documentation fixes that **apply to the released version**. This is the - only reason to touch anything below `R/` and even then it should only affect - roxygen comments. Don't forget to `document()` if you do this! -* Any new vignettes or articles that apply to the released version. +- `README.Rmd` + `README.md`, e.g., if you've updated badges. +- Any documentation fixes that **apply to the released version**. This is the only reason to touch anything below `R/` and even then it should only affect roxygen comments. Don't forget to `document()` if you do this! +- Any new vignettes or articles that apply to the released version. Here are some tips on backporting specific changes into this branch. If you are lucky, there are specific commits in your default branch that contain all the necessary changes. In that case, we can cherry pick such a commit by its SHA: -``` +``` git cherry-pick SHA ``` If that doesn't cover everything, for each file you want to update, identify a Git reference (meaning: a SHA, tag, or branch) where the file is in the desired state. Checkout that specific file path from that specific ref: -``` +``` git checkout REF -- path/to/the/file ``` - + For example, readr recently gained a new vignette that applies to the released version of readr, i.e. it does not document any dev-only features or functions. Here's how to introduce the new vignette from HEAD of `main` into the current branch: -``` +``` git checkout main -- vignettes/column-types.Rmd ``` @@ -249,20 +272,19 @@ Now we will use the `workflow_dispatch` GHA trigger. Go to the Actions page of your repo, maybe via `usethis::browse_github_actions()`. Click on the `pkgdown` workflow. -You should see "This workflow has a workflow_dispatch event trigger." +You should see "This workflow has a workflow_dispatch event trigger."\ (If you don't, that means you didn't do one of the pre-requisites, which is to update to `v2` of the pkgdown workflow.) - + See the "Run workflow" button? -CLICK IT. -In the "Use workflow from" dropdown menu, select the branch you've just made and pushed. +CLICK IT. In the "Use workflow from" dropdown menu, select the branch you've just made and pushed. This should kick off a pkgdown build-and-deploy and, specifically, it should cause updates to the **released** site. - + You can keep this branch around for a while, in case you didn't get everything right the first time or if more things crop up that you'd like backport to the released site, before your next CRAN release. ## Problem-solving Remember GitHub search is a great way to get other people's `_pkgdown.yml` files in front of your eyeballs: -Example query: [`filename:_pkgdown.yml org:tidyverse org:r-lib`](https://github.com/search?q=filename%3A_pkgdown.yml+org%3Atidyverse+org%3Ar-lib) +Example query: [`path:"_pkgdown.yml" AND (org:tidyverse OR org:r-lib)`](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code) For any given `_pkgdown.yml` file on GitHub, remember that its History and Blame can be helpful for seeing how another package's config has evolved over time. diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index dd8d020c8..130be8cf9 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -65,6 +65,7 @@ lang: fr This will be used to set the language of the web page and to translate the English words that pkgdown generates on your site. Current available translations are: +- `ca`: Catalan - `de`: German - `dk`: Danish - `es`: Spanish diff --git a/vignettes/test/widgets.Rmd b/vignettes/test/widgets.Rmd index aee369960..f4200cc90 100644 --- a/vignettes/test/widgets.Rmd +++ b/vignettes/test/widgets.Rmd @@ -15,7 +15,7 @@ Test spacing above widget. ```{r, echo=FALSE} # set seed for reproducible widget id -if (requireNamespace("htmltools", quietly = TRUE)) { +if (requireNamespace("htmlwidgets", quietly = TRUE)) { htmlwidgets::setWidgetIdSeed(42) }