roxygen2-pkgdown

name	roxygen2-pkgdown
description	R package documentation with roxygen2 and pkgdown, including reference topics, articles, and site configuration.

roxygen2 and pkgdown

Overview

Complete reference for roxygen2 documentation syntax and pkgdown site configuration. Covers all roxygen2 tags, cross-referencing, and advanced pkgdown customization.

roxygen2 Fundamentals

Basic Tags

#' @title Short title (optional, first paragraph used if omitted)
#' @description Longer description (optional, second paragraph used if omitted)
#' @details Additional details section
#' @param name Description of parameter
#' @return Description of return value
#' @examples Runnable R code
#' @export Add function to NAMESPACE exports
#' @keywords keyword1 keyword2
#' @author Author Name

Parameter Documentation

#' @param x A numeric vector of values.
#' @param y Character string specifying the method. One of:
#'   - `"method1"`: Description of method 1
#'   - `"method2"`: Description of method 2
#' @param data A data frame containing:
#'   \describe{
#'     \item{col1}{Description of column 1}
#'     \item{col2}{Description of column 2}
#'   }
#' @param ... Additional arguments passed to [other_function()].
#' @param .data Internal use only. Data frame to process.

Return Value Documentation

#' @return A numeric vector of the same length as `x`.

#' @return A list with components:
#'   \describe{
#'     \item{fitted}{Fitted values from the model.}
#'     \item{residuals}{Model residuals.}
#'     \item{coefficients}{Named vector of coefficients.}
#'   }

#' @return A tibble with columns:
#'   * `term`: Character. The term name.
#'   * `estimate`: Numeric. Point estimate.
#'   * `std.error`: Numeric. Standard error.

#' @return Invisibly returns the input `x`.

Examples

#' @examples
#' # Basic usage
#' result <- my_function(1:10)
#'
#' # With options
#' result <- my_function(1:10, method = "fast")
#'
#' \dontrun{
#' # Code that shouldn't be run (e.g., requires authentication)
#' connect_to_database()
#' }
#'
#' \donttest{
#' # Code that runs but is skipped in R CMD check (slow examples)
#' slow_computation(big_data)
#' }
#'
#' @examplesIf interactive()
#' # Only run interactively
#' open_plot_window()

Cross-Referencing

Linking to Functions

#' See [other_function()] for details.
#' This wraps [stats::lm()].
#' Similar to [dplyr::mutate()].
#' See [pkg::function()] from external package.

#' @seealso [related_function()], [another_function()]
#' @seealso
#' * [function1()] for X
#' * [function2()] for Y
#' * [pkg::function3()] for Z

Linking to Topics

#' See [topic-name] for the vignette.
#' See \code{vignette("topic")} for details.
#' See the \href{https://example.com}{website}.

Advanced roxygen2 Tags

Inheritance

#' @inheritParams other_function
#' @inheritDotParams other_function arg1 arg2
#' @inherit other_function return
#' @inherit other_function details
#' @inheritSection other_function Section Name

Function Families

#' @family data import functions
#' @concept data manipulation

Multiple Functions Per File

#' Function A
#' @rdname shared-docs
#' @export
function_a <- function(x) {}

#' Function B
#' @rdname shared-docs
#' @export
function_b <- function(x) {}

#' @rdname shared-docs
#' @usage NULL
#' @aliases function_a function_b

Conditional Exports

#' @rawNamespace if (getRversion() >= "4.0") export(new_function)

S3 Methods

#' @export
#' @method print myclass
print.myclass <- function(x, ...) {}

#' @exportS3Method
print.myclass <- function(x, ...) {}

S4 Classes and Methods

#' MyClass
#'
#' @slot x Numeric slot
#' @slot y Character slot
#'
#' @exportClass MyClass
setClass("MyClass", slots = c(x = "numeric", y = "character"))

#' @exportMethod mymethod
setMethod("mymethod", "MyClass", function(object) {})

Imports

#' @import dplyr
#' @importFrom ggplot2 ggplot aes
#' @importMethodsFrom pkg method
#' @importClassesFrom pkg Class

Markdown in roxygen2

Enable Markdown

# In DESCRIPTION:
Roxygen: list(markdown = TRUE)

Markdown Syntax

#' **Bold** and *italic* text
#'
#' - Bullet point 1
#' - Bullet point 2
#'
#' 1. Numbered item 1
#' 2. Numbered item 2
#'
#' `inline code` and [links](https://example.com)
#'
#' ```r
#' # Code block
#' x <- 1:10
#' ```
#'
#' | Column 1 | Column 2 |
#' |----------|----------|
#' | A        | B        |

pkgdown Configuration

Basic _pkgdown.yml

url: https://user.github.io/pkg/

template:
  bootstrap: 5
  bootswatch: flatly

navbar:
  structure:
    left: [intro, reference, articles, tutorials, news]
    right: [search, github]
  components:
    github:
      icon: fab fa-github
      href: https://github.com/user/pkg

reference:
  - title: Main Functions
    desc: Core functionality
    contents:
      - main_function
      - helper_function
  - title: Utilities
    contents:
      - starts_with("util_")
  - title: internal
    contents:
      - internal_function

articles:
  - title: Getting Started
    navbar: ~
    contents:
      - pkgname
  - title: Advanced Topics
    contents:
      - advanced-usage
      - customization

news:
  releases:
    - text: "Version 1.0.0"
      href: https://github.com/user/pkg/releases/tag/v1.0.0

Reference Organization

reference:
  - title: Data Import
    desc: Functions for importing data
    contents:
      - read_data
      - read_csv_data
      - matches("^read_")

  - title: Data Transformation
    contents:
      - transform_data
      - starts_with("transform_")

  - title: Analysis
    contents:
      - has_concept("analysis")

  - title: Visualization
    contents:
      - has_keyword("plot")

  - subtitle: Core Plots
    contents:
      - plot_main

  - subtitle: Diagnostic Plots
    contents:
      - plot_diagnostics

Custom Styling

template:
  bootstrap: 5
  bootswatch: flatly
  bslib:
    primary: "#0054AD"
    border-radius: 0.5rem
    btn-border-radius: 0.25rem
  includes:
    in_header: |
      <!-- Google Analytics -->
      <script async src="https://www.googletagmanager.com/gtag/js"></script>

Home Page Customization

home:
  title: Package Name
  description: One-line description

  links:
    - text: Learn more
      href: https://example.com

  sidebar:
    structure: [links, license, community, citation, authors, dev]

Articles Configuration

articles:
  - title: Tutorials
    navbar: Tutorials
    contents:
      - articles/getting-started
      - articles/basic-usage

  - title: Advanced
    navbar: Advanced
    contents:
      - articles/advanced-topics

  - title: Internal
    contents:
      - articles/internal-docs
    # Not in navbar

Building pkgdown Site

Build Commands

# Build entire site
pkgdown::build_site()

# Build specific parts
pkgdown::build_home()
pkgdown::build_reference()
pkgdown::build_articles()
pkgdown::build_news()

# Preview locally
pkgdown::preview_site()

# Check site
pkgdown::check_pkgdown()

GitHub Actions Deployment

# .github/workflows/pkgdown.yaml
on:
  push:
    branches: [main, master]
  release:
    types: [published]
  workflow_dispatch:

name: pkgdown

jobs:
  pkgdown:
    runs-on: ubuntu-latest
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: r-lib/actions/setup-pandoc@v2
      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true
      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::pkgdown, local::.
          needs: website
      - name: Build site
        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
        shell: Rscript {0}
      - name: Deploy to GitHub pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          clean: false
          branch: gh-pages
          folder: docs

Workflow

# Development cycle
devtools::document()        # Generate man/ files
devtools::check()           # Check package
pkgdown::build_site()       # Build website

# Quick preview
pkgdown::build_reference_index()
pkgdown::build_article("vignette-name")

Common Patterns

Reexporting Functions

#' @importFrom magrittr %>%
#' @export
magrittr::`%>%`

#' @importFrom rlang .data
#' @export
rlang::.data

Deprecated Functions

#' @description
#' `r lifecycle::badge("deprecated")`
#'
#' This function is deprecated. Use [new_function()] instead.
#'
#' @keywords internal
#' @export
old_function <- function(...) {
  lifecycle::deprecate_warn("1.0.0", "old_function()", "new_function()")
  new_function(...)
}

Internal Functions

#' Internal function
#'
#' @keywords internal
#' @noRd
internal_helper <- function(x) {}