docs: Increase discoverability of functions and articles (#849)

R/accordion.R

@@ -3,6 +3,12 @@
 #' @description
 #' `r lifecycle::badge("experimental")`
 #'
+#' An accordion can be used to organize UI elements and content in a limited
+#' space. It comprises multiple, vertically stacked panels that expand or
+#' collapse when clicked, providing a compact layout that works well for
+#' grouping input elements in a [sidebar()] or for organizing detailed
+#' context-specific information.
+#'
 #' @param ... Named arguments become attributes on the `<div class="accordion">`
 #'   element. Unnamed arguments should be `accordion_panel()`s.
 #' @param id If provided, you can use `input$id` in your server logic to
@@ -17,12 +23,25 @@
 #' @param class Additional CSS classes to include on the accordion div.
 #' @param width,height Any valid CSS unit; for example, height="100%".
 #'
-#' @references <https://getbootstrap.com/docs/5.2/components/accordion/>
-#'
 #' @export
-#' @seealso [accordion_panel_set()]
-#' @examplesIf rlang::is_interactive()
+#' @family Components
+#'
+#' @references bslib's accordion component is derived from the [Bootstrap
+#'   Accordion
+#'   component](https://getbootstrap.com/docs/5.3/components/accordion/).
+#'   Accordions are also featured on the bslib website:
+#'
+#'   * [Get Started: Dashboards](https://rstudio.github.io/bslib/articles/dashboards/index.html#accordions)
+#'   * [Sidebars: Accordions](https://rstudio.github.io/bslib/articles/dashboards/index.html#accordions)
 #'
+#' @seealso [accordion_panel_set()], [accordion_panel_open()] and
+#'   [accordion_panel_close()] programmatically interact with the state of an
+#'   accordion panel.
+#' @seealso [accordion_panel_insert()], [accordion_panel_remove()] and
+#'   [accordion_panel_update()] add or remove accordion panels from an
+#'   accordion.
+#'
+#' @examplesIf rlang::is_interactive()
 #' items <- lapply(LETTERS, function(x) {
 #'   accordion_panel(paste("Section", x), paste("Some narrative for section", x))
 #' })
@@ -167,18 +186,22 @@ accordion_panel <- function(title, ..., value = title, icon = NULL) {
 #' @description
 #' `r lifecycle::badge("experimental")`
 #'
-#' Dynamically (i.e., programmatically) update/modify [`accordion()`]s in a
-#' Shiny app. These functions require an `id` to be provided to the
-#' `accordion()` and must also be called within an active Shiny session.
+#' Dynamically update/modify [`accordion()`]s in a Shiny app. To be updated
+#' programmatically, the [accordion()] must have an `id`. These functions
+#' require an active Shiny session and only work with a running Shiny app.
 #'
 #' @param id an character string that matches an existing [accordion()]'s `id`.
 #' @param values either a character string (used to identify particular
 #'   [accordion_panel()]s by their `value`) or `TRUE` (i.e., all `values`).
 #' @param session a shiny session object (the default should almost always be
 #'   used).
 #'
+#' @seealso [accordion()] and [accordion_panel()] create the accordion
+#'   component.
+#'
 #' @describeIn accordion_panel_set same as `accordion_panel_open()`, except it
 #'   also closes any currently open panels.
+#'
 #' @export
 accordion_panel_set <- function(id, values, session = get_current_session()) {
   send_panel_message(

R/breakpoints.R

@@ -4,13 +4,16 @@
 #' `r lifecycle::badge("experimental")`
 #'
 #' A generic constructor for responsive breakpoints.
+#'
 #' @param sm Values to apply at the `sm` breakpoint.
 #' @param md Values to apply at the `md` breakpoint.
 #' @param lg Values to apply at the `lg` breakpoint.
 #' @param ... Other breakpoints (e.g., `xl`).
 #'
-#' @seealso [layout_columns()]
-#' @references <https://getbootstrap.com/docs/5.3/layout/breakpoints/>
+#' @seealso `breakpoints()` is used by [layout_columns()].
+#' @references Bootstrap's
+#'   [Breakpoints article](https://getbootstrap.com/docs/5.3/layout/breakpoints/)
+#'   provides more detail on breakpoints and how they are used and customized.
 #'
 #' @examples
 #' breakpoints(sm = c(4, 4, 4), md = c(3, 3, 6), lg = c(-2, 8, -2))

R/bs-current-theme.R

@@ -26,7 +26,9 @@
 #'
 #' @param session The current Shiny session (if any).
 #'
-#' @return a [bs_theme()] object.
+#' @return Returns a [bs_theme()] object.
+#'
+#' @family Bootstrap theme functions
 #' @export
 bs_current_theme <- function(session = get_current_session(FALSE)) {
   # If we're able to make a reactive read of the theme, then do it

R/bs-dependencies.R

@@ -10,12 +10,12 @@
 #' @section Sass caching and precompilation:
 #'
 #' If Shiny Developer Mode is enabled (by setting `options(shiny.devmode =
-#' TRUE)` or calling `shiny::devmode(TRUE)`), both \pkg{sass} caching and \pkg{bslib}
-#' precompilation are disabled by default; that is, a call to
+#' TRUE)` or calling `shiny::devmode(TRUE)`), both \pkg{sass} caching and
+#' \pkg{bslib} precompilation are disabled by default; that is, a call to
 #' `bs_theme_dependencies(theme)` expands to `bs_theme_dependencies(theme, cache
-#' = F, precompiled = F)`). This is useful for local development as
-#' enabling caching/precompilation may produce incorrect results if local
-#' changes are made to bslib's source files.
+#' = F, precompiled = F)`). This is useful for local development as enabling
+#' caching/precompilation may produce incorrect results if local changes are
+#' made to bslib's source files.
 #'
 #' @inheritParams bs_theme_update
 #' @param sass_options a [sass::sass_options()] object.
@@ -24,25 +24,24 @@
 #'   precompiled CSS file for the [theme_version()].  If `precompiled = TRUE`
 #'   and a precompiled CSS file exists for the theme object, it will be fetched
 #'   immediately and not compiled. At the moment, we only provide precompiled
-#'   CSS for "stock" builds of Bootstrap (i.e., no theming additions, bootswatch
+#'   CSS for "stock" builds of Bootstrap (i.e., no theming additions, Bootswatch
 #'   themes, or non-default `sass_options`).
 #' @inheritParams sass::sass
 #'
-#' @return a list of HTML dependencies containing Bootstrap CSS, Bootstrap
-#'   JavaScript, and `jquery`. This list may contain additional HTML
+#' @return Returns a list of HTML dependencies containing Bootstrap CSS,
+#'   Bootstrap JavaScript, and `jquery`. This list may contain additional HTML
 #'   dependencies if bundled with the `theme`.
 #'
 #' @export
-#' @seealso [bs_theme()], [bs_dependency()]
-#' @examples
+#' @family Bootstrap theme functions
+#'
+#' @examplesIf rlang::is_interactive()
 #'
 #' # Function to preview the styling a (primary) Bootstrap button
 #' library(htmltools)
 #' button <- tags$a(class = "btn btn-primary", href = "#", role = "button", "Hello")
 #' preview_button <- function(theme) {
-#'   if (interactive()) {
-#'     browsable(tags$body(bs_theme_dependencies(theme), button))
-#'   }
+#'   browsable(tags$body(bs_theme_dependencies(theme), button))
 #' }
 #'
 #' # Latest Bootstrap
@@ -182,12 +181,15 @@ bs_theme_dependencies <- function(
 #' @param .sass_args A list of additional arguments to pass to
 #'   [sass::sass_partial()].
 #' @inheritParams htmltools::htmlDependency
-#' @references
-#' <https://rstudio.github.io/bslib/articles/custom-components.html>
 #'
+#' @references
+#'   * [Theming: Custom components](https://rstudio.github.io/bslib/articles/custom-components/index.html)
+#'     gives a tutorial on creating a dynamically themable custom component.
 #'
 #' @return `bs_dependency()` returns an [htmltools::htmlDependency()] and
 #'   `bs_dependency_defer()` returns an [htmltools::tagFunction()]
+#'
+#' @family Bootstrap theme functions
 #' @export
 bs_dependency <- function(input = list(), theme, name, version,
   cache_key_extra = NULL, .dep_args = list(), .sass_args = list())
@@ -242,6 +244,7 @@ bs_dependency <- function(input = list(), theme, name, version,
   do.call(htmlDependency, c(dep_args, .dep_args))
 }
 
+#' @rdname bs_dependency
 #' @param func a _non-anonymous_ function, with a _single_ argument.
 #'   This function should accept a [bs_theme()] object and return a single
 #'   [htmlDependency()], a list of them, or `NULL`.
@@ -251,12 +254,10 @@ bs_dependency <- function(input = list(), theme, name, version,
 #'   that you may want to avoid memoisation if `func` relies on side-effects
 #'   (e.g., files on-disk) that need to change for each themable widget
 #'   instance.
-#' @export
-#'
-#' @examples
 #'
-#' \dontrun{
+#' @export
 #'
+#' @examplesIf rlang::is_interactive()
 #' myWidgetVersion <- "1.2.3"
 #'
 #' myWidgetDependency <- function() {
@@ -306,9 +307,6 @@ bs_dependency <- function(input = list(), theme, name, version,
 #'     myWidgetDependency()
 #'   )
 #' }
-#' }
-#'
-#' @rdname bs_dependency
 bs_dependency_defer <- function(func, memoise = TRUE) {
   # func() most likely calls stuff like sass_file() and bs_dependency() ->
   # sass_partial() -> sass() (e.g., see example section above) Even though

R/bs-global.R

@@ -1,36 +1,58 @@
 #' Global theming
 #'
-#' `bs_global_theme()` creates a new (global) Bootstrap Sass theme which
-#' [bs_theme_dependencies()] (or [sass_partial()]) can consume (their `theme`
-#' argument defaults to `bs_global_get()`, which get the current global theme).
+#' `bs_global_theme()` creates and sets the global Bootstrap Sass theme. This
+#' theme is typically found by [bs_theme_dependencies()] in the app or document
+#' where the global theme is being used. You can obtain the current global theme
+#' with [bs_global_get()] or directly set the global theme with
+#' [bs_global_set()].
 #'
 #' @inheritParams bs_theme
 #'
-#' @return functions that modify the global theme (e.g., `bs_global_set()`)
+#' @return Functions that modify the global theme (e.g., `bs_global_set()`)
 #'   invisibly return the previously set theme. `bs_global_get()` returns the
 #'   current global theme.
 #'
-#' @seealso [bs_theme()], [bs_theme_preview()]
-#' @examples
+#' @family Bootstrap theme functions
 #'
+#' @examples
 #' # Remember the global state now (so we can restore later)
 #' theme <- bs_global_get()
+#'
 #' # Use Bootstrap 3 (globally) with some theme customization
 #' bs_global_theme(3, bg = "#444", fg = "#e4e4e4", primary = "#e39777")
-#' if (interactive()) bs_theme_preview(with_themer = FALSE)
+#' if (rlang::is_interactive()) {
+#'   bs_theme_preview(with_themer = FALSE)
+#' }
+#'
 #' # If no global theme is active, bs_global_get() returns NULL
 #' bs_global_clear()
 #' bs_global_get()
+#'
 #' # Restore the original state
 #' bs_global_set(theme)
 #'
 #' @export
-bs_global_theme <- function(version = version_default(), bootswatch = NULL, bg = NULL, fg = NULL,
-                            primary = NULL, secondary = NULL, success = NULL, info = NULL, warning = NULL,
-                            danger = NULL, base_font = NULL, code_font = NULL, heading_font = NULL, ...) {
+bs_global_theme <- function(
+  version = version_default(),
+  bootswatch = NULL,
+  bg = NULL,
+  fg = NULL,
+  primary = NULL,
+  secondary = NULL,
+  success = NULL,
+  info = NULL,
+  warning = NULL,
+  danger = NULL,
+  base_font = NULL,
+  code_font = NULL,
+  heading_font = NULL,
+  ...
+) {
   bs_global_set(bs_theme(
-    version, bootswatch,
-    bg = bg, fg = fg,
+    version,
+    bootswatch,
+    bg = bg,
+    fg = fg,
     primary = primary,
     secondary = secondary,
     success = success,

R/bs-remove.R

@@ -1,20 +1,33 @@
 #' Remove or retrieve Sass code from a theme
 #'
+#' A Bootstrap theme created with [bs_theme()] is comprised of
+#' [many Sass layers](https://rstudio.github.io/sass/articles/sass.html#layering).
+#' `bs_remove()` and `bs_retrieve()` allow you to remove or retrieve an
+#' individual layer, either to reduce the size of the compiled CSS or to extract
+#' styles from a theme.
+#'
 #' @inheritParams bs_theme_update
 #' @param ids a character vector of ids
 #'
-#' @return a modified [bs_theme()] object.
+#' @return Returns a modified [bs_theme()] object.
 #'
 #' @export
+#' @family Bootstrap theme functions
+#'
 #' @examples
+#' bs4 <- bs_theme(version = 4)
+#'
+#' # Retrieve sass bundle for print styles
+#' bs_retrieve(bs4, "_print", include_unnamed = FALSE)
 #'
 #' # Remove CSS rules for print and carousels
-#' bs4 <- bs_theme(version = 4)
-#' bs_remove(bs4, c("_print", "_carousel"))
+#' bs4_no_print <- bs_remove(bs4, c("_print", "_carousel"))
+#' suppressWarnings(
+#'   bs_retrieve(bs4_no_print, "_print", include_unnamed = FALSE)
+#' )
 #'
 #' # Remove BS3 compatibility layer
-#' bs_remove(bs4, "bs3compat")
-#'
+#' bs4_no_compat <- bs_remove(bs4, "bs3compat")
 bs_remove <- function(theme, ids = character(0)) {
   ids <- retain_valid_ids(theme, ids)
   sass_bundle_remove(theme, ids)