docs.artalytics.dev

Build and Deploy

Central documentation hub for Artalytics R packages. Provides a unified landing page with auto-discovery of pkgdown documentation sites.

Live Site: https://docs.artalytics.dev

Prerequisites

  • Quarto (v1.4+)
  • R (v4.1+)
  • R packages: fs, stringr, data.table (for package discovery script)

Project Structure

docs.artalytics.dev/
├── _quarto.yml             # Quarto project configuration
├── index.qmd               # Landing page with dynamic package listings
├── styles.scss             # Custom SCSS (Bootstrap 5 overrides)
├── _scripts/
│   └── discover_packages.R # Scans r/ and extracts package metadata
├── .github/
│   └── workflows/
│       └── pages.yaml      # Build Quarto + deploy to GitHub Pages
├── CNAME                   # Custom domain configuration
├── NEWS.md                 # Changelog
└── r/                      # pkgdown sites (auto-populated by package CIs)
    ├── artutils/
    ├── artcore/
    ├── artgemini/
    └── .../

How It Works

Architecture

┌─────────────────────┐     ┌──────────────────────┐
│  Package Repos      │     │  docs.artalytics.dev │
│  (artutils, etc.)   │     │                      │
│                     │     │  ┌────────────────┐  │
│  pkgdown workflow ──┼────►│  │ r/{package}/   │  │
│  builds & pushes    │     │  └────────────────┘  │
└─────────────────────┘     │          ▲           │
                            │          │           │
                            │  ┌───────┴────────┐  │
                            │  │ index.qmd      │  │
                            │  │ (discovers &   │  │
                            │  │  lists pkgs)   │  │
                            │  └────────────────┘  │
                            └──────────────────────┘
  1. Package CI: Each R package has a pkgdown workflow that builds documentation and pushes to r/<package-name>/ in this repo
  2. Quarto Build: The landing page runs R code to scan r/ and extract metadata from each pkgdown site
  3. Auto-Discovery: Package descriptions are pulled from <meta name="description"> tags in pkgdown’s index.html

Package Discovery

The _scripts/discover_packages.R script: - Scans r/ for subdirectories - Reads each package’s index.html to extract the description - Returns structured metadata used by index.qmd to render package cards - Packages without index.html are marked “coming soon”

Local Development

Preview

# Start live preview server (auto-reloads on changes)
quarto preview

Build

# Render the site to _site/
quarto render

# Verify output
ls _site/

Testing Package Discovery

# Test the discovery script directly
source("_scripts/discover_packages.R")
packages <- discover_packages("r")
print(packages)

# View as data.table
packages_dt("r")

Deployment

GitHub Pages (Automatic)

The site deploys automatically on push to main via .github/workflows/pages.yaml:

  1. Checkout repository
  2. Setup R and Quarto
  3. Run quarto render
  4. Copy r/ directory to _site/r/
  5. Deploy _site/ to GitHub Pages

Posit Connect Cloud (Manual)

For publishing to Posit Connect Cloud:

# First-time setup (interactive)
quarto publish connect

# Subsequent deployments
quarto publish connect --no-prompt

Note: Ensure r/ directory contents are included. The workflow copies pkgdown sites after Quarto render.

Adding a New Package

When creating a new Artalytics R package:

  1. Add pkgdown workflow to your package repo:

    # .github/workflows/pkgdown.yaml
jobs:
  docs:
    uses: artalytics/.github/.github/workflows/pkgdown.yaml@main
    secrets: inherit

  2. Configure secrets: Ensure GH_PAT has write access to this repo

  3. Trigger workflow: Push to main or manually dispatch

  4. Verify: The package appears automatically on next docs site build

Troubleshooting

Issue Solution
Package not appearing Check r/<pkg>/index.html exists; trigger docs site rebuild
Description shows “Documentation for X” Verify pkgdown site has <meta name="description"> tag
Quarto render fails Ensure R and required packages installed (fs, stringr)
Styles not updating Clear .quarto/ cache: rm -rf .quarto/

Development

For AI agent instructions and coding standards, see the organization-level documentation in artalytics/.agents.

Proprietary - Artalytics