Roxygen2 Pkgdown

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 = "4.0") export(new_function)

S3 Methods

#' @export
#' @method print myclass
print.myclass 

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) {}

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: choxos
• Source: choxos/BiostatAgent
• License: MIT

Install and usage instructions live in the source repository linked above.