Document a pipeline from scratch

Everything tardoc needs is a _targets.R and the R files it sources. This builds a three-target pipeline in a temporary directory, runs it, and documents it.

proj <- file.path(tempdir(), "demo-pipeline")
dir.create(file.path(proj, "R"), recursive = TRUE, showWarnings = FALSE)

writeLines(c(
  "#' Read the raw readings",
  "#'",
  "#' @param n Number of observations to simulate.",
  "#' @return A data frame of readings.",
  "read_readings <- function(n = 200) {",
  "  set.seed(1)",
  "  data.frame(station = rep(c('A', 'B'), length.out = n),",
  "             temp_c   = round(rnorm(n, 12, 30), 1))",
  "}",
  "",
  "#' Drop impossible readings",
  "#'",
  "#' @param readings Raw readings.",
  "#' @param min_c,max_c Rated range of the probe, in Celsius.",
  "#' @return The readings inside the probe's range.",
  "clean_readings <- function(readings, min_c = -40, max_c = 85) {",
  "  # Out-of-range values mean a probe was being serviced, not that the",
  "  # station was that cold. Dropping is deliberate: imputing would invent",
  "  # readings, and the counts downstream are reported as observed.",
  "  readings[readings$temp_c >= min_c & readings$temp_c <= max_c, ]",
  "}"
), file.path(proj, "R", "functions.R"))

writeLines(c(
  "library(targets)",
  "tar_source('R')",
  "",
  "list(",
  "  tar_target(raw, read_readings(400),",
  "             description = 'Simulated logger export'),",
  "  tar_target(clean, clean_readings(raw),",
  "             description = 'Readings inside the probe range'),",
  "  tar_target(by_station, aggregate(temp_c ~ station, clean, mean))",
  ")"
), file.path(proj, "_targets.R"))

Run it. callr_function = NULL reads _targets.R in this session rather than a subprocess, which is what makes this work in a browser as well as on a desktop.

withr::with_dir(proj, targets::tar_make(callr_function = NULL))
#>+ raw dispatched
#>✔ raw completed [1ms, 1.25 kB]
#>+ clean dispatched
#>✔ clean completed [0ms, 2.07 kB]
#>+ by_station dispatched
#>✔ by_station completed [5ms, 157 B]
#>✔ ended pipeline [162ms, 3 completed, 0 skipped]

Now document it. One call writes the markdown, the viewer and the WASM analytics page.

tardoc::document_targets(project_path = proj, pkg_name = "Demo pipeline")
#>Directories ready under: /tmp/RtmplUFPjF/demo-pipeline/tardoc
#>Store found -- run metadata loaded.
#>0 of 3 targets are outdated.
#>Loaded 3 targets.
#>Target: raw
#>Target: clean
#>Target: by_station
#>3 target pages written.
#>  Function: read_readings
#>  Function: clean_readings
#>2 function pages written.
#>Run history: 1 snapshot in /tmp/RtmplUFPjF/demo-pipeline/tardoc/history.json
#>Notes stubs ready under: /tmp/RtmplUFPjF/demo-pipeline/tardoc/notes
#>Search index written: /tmp/RtmplUFPjF/demo-pipeline/tardoc/search_index.json
#>llms.txt written: /tmp/RtmplUFPjF/demo-pipeline/llms.txt
#>Viewer written: /tmp/RtmplUFPjF/demo-pipeline/tardoc/viewer.html
#>WASM viewer written: /tmp/RtmplUFPjF/demo-pipeline/tardoc/wasm_analytics.html
#>Analytics viewer written: /tmp/RtmplUFPjF/demo-pipeline/tardoc/analytics.html
#>
#>Done.
#>  Tier 1 (static):     /tmp/RtmplUFPjF/demo-pipeline/tardoc/viewer.html
#>  Tier 2 (WASM):       /tmp/RtmplUFPjF/demo-pipeline/tardoc/wasm_analytics.html
#>  Tier 3 (server):     tardoc::view_tardoc_db()
#>  Tier 3 + chat:       tardoc::view_tardoc_db(llm_chat = ellmer::chat_openai())
#>  MCP (Claude Desktop): tardoc::serve_tardoc_mcp()
#>  LLMs:                /tmp/RtmplUFPjF/demo-pipeline/llms.txt
#>
#>Tip: rerun with llm=TRUE to auto-generate missing descriptions.
#>
list.files(file.path(proj, "tardoc"), recursive = TRUE)
#> [1] "analytics.html"                    "functions/clean_readings.md"      
#> [3] "functions/read_readings.md"        "history.json"                     
#> [5] "notes/functions/clean_readings.md" "notes/functions/read_readings.md" 
#> [7] "notes/index.md"                    "notes/targets/by_station.md"      
#> [9] "notes/targets/clean.md"            "notes/targets/raw.md"             
#>[11] "search_index.json"                 "tardoc_analytics.json"            
#>[13] "targets/by_station.md"             "targets/clean.md"                 
#>[15] "targets/raw.md"                    "viewer.html"                      
#>[17] "wasm_analytics.html"              

Each target gets a markdown page carrying its status, command, timings and the functions it calls — this is what the viewer renders:

cat(readLines(file.path(proj, "tardoc", "targets", "clean.md")), sep = "\n")
# Target: clean

> Readings inside the probe range

<!-- tardoc:generated -->
## Details

| Field | Value |
|---|---|
| **Status** | Up-to-date |
| **Last built** | 2026-10-20 17:05:18.207992 |
| **Last run** | completed |
| **Runtime** | 0 ms |
| **Size** | 2.07 kB |

## Command

```r
clean_readings(raw)
```

## Functions called

[`clean_readings`](../functions/clean_readings.md), [`read_readings`](../functions/read_readings.md)

## Local dependency graph

```mermaid
%%{init:{'theme':'dark','themeVariables':{'lineColor':'#a6adc8','edgeLabelBackground':'#1e1e2e'}}}%%
graph LR
    clean_readings --> clean
    raw --> clean
    read_readings --> raw
    clean --> by_station
    style clean fill:#6b48cc,color:#fff,stroke:#4a32a0
```
<!-- tardoc:end -->

And each function gets one, with its roxygen rendered and its source kept verbatim — comments included, because the source is read from the file rather than reconstructed from the parsed function:

cat(readLines(file.path(proj, "tardoc", "functions", "clean_readings.md")),
    sep = "\n")
# Function: `clean_readings`

<!-- tardoc:generated -->
## Documentation

# Drop impossible readings

## Description

Drop impossible readings

## Usage

```r
clean_readings(readings, min_c = -40, max_c = 85)
```

## Arguments

* `readings`: Raw readings.
* `min_c, max_c`: Rated range of the probe, in Celsius.

## Value

The readings inside the probe's range.



## Source

Defined in `functions.R`

```r
clean_readings <- function(readings, min_c = -40, max_c = 85) {
  # Out-of-range values mean a probe was being serviced, not that the
  # station was that cold. Dropping is deliberate: imputing would invent
  # readings, and the counts downstream are reported as observed.
  readings[readings$temp_c >= min_c & readings$temp_c <= max_c, ]
}
```
<!-- tardoc:end -->