diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 087f0b05f..ed7650c73 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -19,6 +19,8 @@ jobs: group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write steps: - uses: actions/checkout@v3 diff --git a/DESCRIPTION b/DESCRIPTION index 82bea1e5b..b61cdfe2d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,12 +2,12 @@ Package: roxygen2 Title: In-Line Documentation for R Version: 7.2.3 Authors@R: c( - person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre", "cph"), + person("Hadley", "Wickham", , "hadley@posit.co", role = c("aut", "cre", "cph"), comment = c(ORCID = "0000-0003-4757-117X")), person("Peter", "Danenberg", , "pcd@roxygen.org", role = c("aut", "cph")), person("Gábor", "Csárdi", , "csardi.gabor@gmail.com", role = "aut"), person("Manuel", "Eugster", role = c("aut", "cph")), - person("RStudio", role = c("cph", "fnd")) + person("Posit Software, PBC", role = c("cph", "fnd")) ) Description: Generate your Rd documentation, 'NAMESPACE' file, and collation field using specially formatted comments. Writing @@ -18,7 +18,7 @@ License: MIT + file LICENSE URL: https://roxygen2.r-lib.org/, https://github.com/r-lib/roxygen2 BugReports: https://github.com/r-lib/roxygen2/issues Depends: - R (>= 3.3) + R (>= 3.6) Imports: brew, cli (>= 3.3.0), @@ -27,7 +27,7 @@ Imports: knitr, methods, pkgload (>= 1.0.2), - purrr (>= 0.3.3), + purrr (>= 1.0.0), R6 (>= 2.1.2), rlang (>= 1.0.6), stringi, @@ -51,5 +51,4 @@ Config/testthat/edition: 3 Encoding: UTF-8 Language: en-GB Roxygen: list(markdown = TRUE, load = "installed") -RoxygenNote: 7.2.2.9000 -SystemRequirements: C++11 +RoxygenNote: 7.2.3.9000 diff --git a/README.md b/README.md index 43eef07d0..217bac475 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# roxygen2 +# roxygen2 roxygen2 website [![CRAN status](https://www.r-pkg.org/badges/version/roxygen2)](https://CRAN.R-project.org/package=roxygen2) -[![R-CMD-check](https://github.com/r-lib/roxygen2/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/roxygen2/actions) +[![R-CMD-check](https://github.com/r-lib/roxygen2/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/roxygen2/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/r-lib/roxygen2/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/roxygen2?branch=main) @@ -11,12 +11,12 @@ The premise of roxygen2 is simple: describe your functions in comments next to t ## Installation ```R -# Install devtools from CRAN +# Install roxygen2 from CRAN install.packages("roxygen2") # Or the development version from GitHub: -# install.packages("devtools") -devtools::install_github("r-lib/roxygen2") +# install.packages("pak") +pak::pak("r-lib/roxygen2") ``` ## Usage diff --git a/man/figures/logo.png b/man/figures/logo.png index 2188d2ce7..13709c5e3 100644 Binary files a/man/figures/logo.png and b/man/figures/logo.png differ diff --git a/pkgdown/favicon/apple-touch-icon-120x120.png b/pkgdown/favicon/apple-touch-icon-120x120.png index 35c99bb04..6a7b228fc 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 new file mode 100644 index 000000000..048683fe0 Binary files /dev/null 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 new file mode 100644 index 000000000..b5ce9b4b7 Binary files /dev/null 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 a03b2295d..fd50d1d79 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 aa9900c82..6df2b3178 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 35c99bb04..93664fd71 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 40fffa9b3..ccab120f0 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 9418c110a..8da12cd70 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 5b4d1bade..401fb1a0a 100644 Binary files a/pkgdown/favicon/favicon.ico and b/pkgdown/favicon/favicon.ico differ diff --git a/vignettes/index-crossref.Rmd b/vignettes/index-crossref.Rmd index e15a64a0b..98a7ad4bd 100644 --- a/vignettes/index-crossref.Rmd +++ b/vignettes/index-crossref.Rmd @@ -37,7 +37,7 @@ A function can be a member of multiple families. By default `@family {family}`, will generate the see also text "Other {family}:", so the `@family` name should be plural (i.e., "model building helpers" not "model building helper"). -If you want to override default title, you can provide an `rd_family_title` element in a list stored in `man/roxygen/meta.R`: +If you want to override the default title, you can provide an `rd_family_title` element in a list stored in `man/roxygen/meta.R`: ```{r, eval = FALSE} list( diff --git a/vignettes/rd-other.Rmd b/vignettes/rd-other.Rmd index 8c9cf0ef6..dab6d5f5b 100644 --- a/vignettes/rd-other.Rmd +++ b/vignettes/rd-other.Rmd @@ -42,6 +42,8 @@ This means you need to document them in a slightly different way: instead of doc #' \item{depth}{total depth percentage = z / mean(x, y) = 2 * z / (x + y) (43--79)} #' \item{table}{width of top of diamond relative to widest point (43--95)} #' } +#' +#' @source {ggplot2} tidyverse R package. ``` Note the use of two additional tags that are particularly useful for documenting data: diff --git a/vignettes/rd.Rmd b/vignettes/rd.Rmd index e9556cef2..d1b8b7452 100644 --- a/vignettes/rd.Rmd +++ b/vignettes/rd.Rmd @@ -80,7 +80,7 @@ This is unnecessary unless you want to have a multi-paragraph description, bulle ## Functions -Functions are the mostly commonly documented objects. +Functions are the most commonly documented objects. Functions require three tags: `@param`, `@returns`, and `@examples`. ### Inputs @@ -129,10 +129,10 @@ This way, the code evaluating whether the example can be run is not shown to use Instead of including examples directly in the documentation, you can put them in separate files and use `@example path/relative/to/package/root` to insert them into the documentation. -All functions must have a documented return value for initial CRAN submission. +All functions must have examples for initial CRAN submission. ### Usage In most case, the function usage (which appears beneath the description in the generates docs) will be automatically derived from the function specification. -For the cases where it is not, please [file an issue](https://github.com/r-lib/roxygen2/issues) and use `@usage` to override the default with you want. +For the cases where it is not, please [file an issue](https://github.com/r-lib/roxygen2/issues) and use `@usage` to override the default with what you want. If you want to suppress the usage altogether (which is sometimes useful for internal or deprecated functions), you can use `@usage NULL`. diff --git a/vignettes/reuse.Rmd b/vignettes/reuse.Rmd index fd46c6de4..e1679c227 100644 --- a/vignettes/reuse.Rmd +++ b/vignettes/reuse.Rmd @@ -19,7 +19,7 @@ knitr::opts_chunk$set( roxygen2 provides several ways to avoid repeating yourself in code documentation, while assembling information from multiple places in one documentation file: -- Combine documentation for closely related functions into a single file with `@describe` in or `@rdname`. +- Combine documentation for closely related functions into a single file with `@describeIn` or `@rdname`. - Inherit components from another topic with `@inheritParams`, `@inheritSection`, or `@inherit`. @@ -37,7 +37,7 @@ Use it when all functions have the same (or very similar) arguments. ### `@describeIn` -Use `@describeIn ` to document mutiple functions together. +Use `@describeIn ` to document multiple functions together. It generates a new section named "**Related functions and methods**", further divided into subsections by the type of relationship between the source and the destination documentation. Each subsection contains a bulleted list describing the function with the specified ``. @@ -170,7 +170,7 @@ Note that the evaluation environment is deliberately a child of the package that ## Child documents -You can use the same `.Rmd` or `.md` document in the documentation, `README.Rmd`, and vignettes but using child documents: +You can use the same `.Rmd` or `.md` document in the documentation, `README.Rmd`, and vignettes by using child documents: ```{r child = "common.Rmd"}`r ''` ```