-- B --
build_dag_graph()
build_site_config()
-- C --
critical_path()
-- D --
dag_layout()
diff_run_history()
document_targets()
-- G --
generate_all_function_pages()
generate_all_target_pages()
generate_analytics_data()
generate_analytics_viewer()
generate_llm_content()
generate_llms_txt()
generate_notes()
generate_reactflow_graph()
generate_search_index()
generate_tardoc_db()
generate_viewer()
generate_wasm_viewer()
get_fn_docs()
get_target_network_dependencies()
-- I --
inject_quack_session()
-- L --
load_targets_data()
-- M --
moxygenise()
moxygenise_file()
-- P --
pipeline_profile()
-- R --
read_note()
read_overview()
read_run_history()
record_run_snapshot()
-- S --
score_grouping()
serve_tardoc_mcp()
setup_site_dirs()
-- T --
tardoc
tardoc-package
target_groups()
-- V --
view_tardoc()
view_tardoc_db()
view_wasm_analytics()
Auto-generates documentation for a 'targets' pipeline from '_targets.R' and the roxygen comments beside it: one markdown file per target and per function, plus a self-contained HTML viewer with an interactive dependency graph, fuzzy search, build status, timings, per-branch detail and verbatim function source. Freshness, the critical path and a diff against the previous build are reported alongside. Optional layers add a DuckDB WASM analytics page that opens from the filesystem, a local DuckDB server with full-text and semantic search, an LLM chat interface over the pipeline database via 'ellmer', and the same database as an MCP server for use with coding agents.
Maintainer: Cathal Byrne cathal.byrne@cso.ie
Authors:
Cathal Byrne cathal.byrne@cso.ie
Useful links:
Report bugs at https://github.com/CathalByrneGit/tardoc/issues
Turns targets_data into the {nodes, edges} shape the viewer's graph
consumes, with positions already assigned by dag_layout().
build_dag_graph(targets_data, include_functions = TRUE, groups = NULL)
targets_data |
Output of |
include_functions |
Logical. Include function vertices as nodes.
|
groups |
Optional named character vector of group label per target,
from |
Nodes come from tar_network()'s vertices, which already carry type
(stem / pattern / function), a branch count, runtime and size. They are
enriched from the manifest (command, branching pattern, storage settings) and
the metadata (errors, warnings, build time) so a reader can inspect a target
without leaving the graph.
A list with nodes and edges, and groups when grouped.
All generated content goes into site_dir (default "tardoc") inside the
project root. No renderer is required – output is plain markdown files plus
a self-contained HTML viewer.
build_site_config(project_path = ".", site_dir = "tardoc", repo_url = NULL)
project_path |
Path to the targets project root. Default |
site_dir |
Name of the output subfolder. Default |
repo_url |
Base URL of the hosted repo, e.g.
|
A named list used as cfg throughout the package.
The chain of targets whose runtimes sum to the largest total. Since every target on it waits for the one before, its total is a lower bound on the wall-clock time of a full rebuild however many workers you give it.
critical_path(nodes, edges)
nodes |
A data frame or list with |
edges |
A data frame with |
Targets with no recorded runtime count as zero rather than dropping out, so a partially built pipeline still returns a sensible path.
A character vector of target names, ordered from root to leaf. Empty when there are no nodes.
critical_path(
nodes = data.frame(name = c("a", "b", "c"), seconds = c(1, 10, 2)),
edges = data.frame(from = c("a", "a"), to = c("b", "c"))
)
#> [1] "a" "b"
Computes a left-to-right layered layout: each node's column is its longest-path depth from a root, and nodes sharing a column are stacked vertically and centred against the tallest column.
dag_layout(nodes, edges, x_spacing = 220, y_spacing = 90)
nodes |
Character vector of node names. |
edges |
A data frame or list with |
x_spacing |
Horizontal distance between layers, in pixels. |
y_spacing |
Vertical distance between stacked nodes, in pixels. |
Cycles cannot occur in a targets pipeline, but a malformed edge list could
contain one. Rather than looping forever, any node still unresolved once no
further progress is possible is placed in the last computed layer.
A data frame with name, layer, x and y.
dag_layout(
nodes = c("a", "b", "c"),
edges = data.frame(from = c("a", "b"), to = c("b", "c"))
)
#> name layer x y
#> 1 a 0 0 0
#> 2 b 1 220 0
#> 3 c 2 440 0
Compare the two most recent snapshots
diff_run_history(history, slower_by = 0.25)
history |
A list of snapshots from |
slower_by |
Numeric. Relative change in runtime counted as meaningful. Defaults to 0.25, i.e. a quarter slower or faster; anything smaller is noise on a re-run rather than a regression. |
NULL when there is nothing to compare, otherwise a list with
from, to (the two timestamps) and character vectors added,
removed, rebuilt, status_changed, slower, faster, grew,
shrank – each describing one target per element.
Generates all tardoc output: markdown pages, Tier 1 viewer, Tier 2 WASM
analytics viewer, Tier 3/4 server analytics database, and llms.txt.
document_targets(
project_path = ".",
site_dir = "tardoc",
pkg_name = "targets docs",
pkg_desc = "",
repo_url = NULL,
llm = FALSE,
llm_chat = NULL,
llm_provider = "openai",
llm_model = NULL,
llm_api_key = NULL,
llm_base_url = NULL,
check_outdated = TRUE,
group_by = "auto"
)
project_path |
Path to the targets project root. Default |
site_dir |
Subfolder for all generated content. Default |
pkg_name |
Title shown in viewer headers. |
pkg_desc |
One-paragraph project description (used in |
repo_url |
Optional base URL of the hosted repo for source links. |
llm |
Logical. Auto-generate missing target descriptions and
function explanations via an LLM. Default |
llm_chat |
A pre-configured ellmer |
llm_provider |
Provider for LLM calls. One of |
llm_model |
Model name. |
llm_api_key |
API key. |
llm_base_url |
Base URL for |
check_outdated |
Logical. Call |
group_by |
How the pipeline overview may be collapsed into groups:
|
Tiers produced:
Tier 1: viewer.html – opens as file://, no server
Tier 2: wasm_analytics.html – DuckDB WASM, opens as file://, data embedded
Tier 3/4: tardoc.duckdb – for view_tardoc_db() with Quack + LLM chat
The cfg list, invisibly.
# Minimal -- Tier 1 + 2 always, Tier 3 if duckdb installed
document_targets(pkg_name = "My pipeline")
view_tardoc() # Tier 1: file:// viewer
view_wasm_analytics() # Tier 2: WASM, file://
view_tardoc_db() # Tier 3: server + Quack
# With LLM descriptions (OpenAI by default, reads OPENAI_API_KEY)
document_targets(llm = TRUE)
# Local LLM via Ollama
document_targets(llm = TRUE, llm_provider = "ollama", llm_model = "llama3.2")
# Analytics + chat with any provider
view_tardoc_db(llm_chat = ellmer::chat_openai())
view_tardoc_db(llm_chat = ellmer::chat_ollama("llama3.2"))
Writes one .md file per function into cfg$functions_dir. Roxygen docs
and source code are inside the <!-- tardoc:generated --> block and
updated on every run.
generate_all_function_pages(cfg)
cfg |
A site config list. |
A character vector of function names, invisibly.
Writes one .md file per target into cfg$targets_dir. Each file contains
a mermaid local dependency diagram, command, status, and function links.
Only the region between <!-- tardoc:generated --> markers is overwritten
on re-runs – any content outside those markers is preserved.
generate_all_target_pages(targets_data, cfg)
targets_data |
Output of |
cfg |
A site config list. |
A character vector of target names, invisibly.
Writes tardoc_analytics.json into cfg$site_path. This is a richer
dataset than search_index.json – it includes the full edge list (for
graph traversal), notes content, and all fields needed for SQL analytics.
The DuckDB WASM analytics viewer loads this file and ingests it into
in-browser tables.
generate_analytics_data(targets_data, function_names, cfg)
targets_data |
Output of |
function_names |
Character vector of function names. |
cfg |
A site config list. |
Path to tardoc_analytics.json invisibly.
Writes analytics.html into cfg$site_path using
inst/templates/analytics.html. This file is a server template:
open it via view_tardoc_db(), not directly in a browser.
generate_analytics_viewer(cfg, pkg_name = "targets docs")
cfg |
A site config list. |
pkg_name |
Character. Project title shown in the viewer header. |
Path to analytics.html invisibly.
Fills in descriptions for targets that have none and adds a plain-language
explanation to each function page. Requires the ellmer package.
generate_llm_content(
targets_data,
function_names,
cfg,
llm_chat = NULL,
provider = "openai",
model = NULL,
api_key = NULL,
base_url = NULL
)
targets_data |
Output of |
function_names |
Character vector of function names to explain. |
cfg |
A site config list. |
llm_chat |
An existing |
provider |
Character. One of |
model |
Character. Model name. Defaults to the provider's own
default when |
api_key |
Character. API key. When |
base_url |
Character. Base URL for |
Invisibly NULL; called for its side effect of rewriting the
generated blocks of the target and function markdown pages.
Writes a plain markdown file at the package root that summarises the entire targets project in a format any LLM can read directly – no HTML parsing or indexing required. Follows the llmstxt.org convention.
generate_llms_txt(
targets_data,
cfg,
project_title = "Targets project",
project_desc = ""
)
targets_data |
Output of |
cfg |
A site config list. |
project_title |
Character. Title shown at the top of the file. |
project_desc |
Character. One-paragraph description of the project. |
Path to llms.txt invisibly.
Creates empty note files under cfg$notes_targets and
cfg$notes_functions for any target or function that does not already
have one. Existing note files are never touched – they are
entirely user-owned.
generate_notes(target_names, function_names, cfg)
target_names |
Character vector of target names. |
function_names |
Character vector of function names. |
cfg |
A site config list. |
Note files live at:
tardoc/notes/index.md – the project overview, shown on the viewer's
home page under the title
tardoc/notes/targets/TARGET_NAME.md
tardoc/notes/functions/FUNCTION_NAME.md
Invisibly NULL.
Writes reactflow_graph.html into cfg$site_path: an interactive,
pan-and-zoom rendering of the target DAG. Experimental, and not part of a
default document_targets() run.
generate_reactflow_graph(targets_data, cfg, pkg_name = "targets docs")
targets_data |
Output of |
cfg |
A site config list. |
pkg_name |
Character. Project title. |
Path to reactflow_graph.html, invisibly.
Writes search_index.json into cfg$site_path. The viewer uses this for
instant full-text search across all targets and functions without any
server-side infrastructure.
generate_search_index(targets_data, function_names, cfg)
targets_data |
Output of |
function_names |
Character vector of function names from
|
cfg |
A site config list. |
Path to search_index.json invisibly.
Creates tardoc/tardoc.duckdb. Attempts each capability layer in turn;
skips cleanly if the required extension is unavailable. The _meta table
records which capabilities succeeded so the analytics viewer can adapt its
UI accordingly.
generate_tardoc_db(targets_data, function_names, cfg, db_extensions = FALSE)
targets_data |
Output of |
function_names |
Character vector of function names. |
cfg |
A site config list. |
db_extensions |
Logical. When |
Path to tardoc.duckdb invisibly, or NULL if the duckdb
package is not installed.
Writes viewer.html into cfg$site_path by loading
inst/templates/viewer.html and substituting data placeholders.
No R string escaping – the template is plain HTML with real JavaScript.
generate_viewer(
targets_data,
function_names,
cfg,
pkg_name = "targets docs",
group_by = "auto"
)
targets_data |
Output of |
function_names |
Character vector of function names. |
cfg |
A site config list. |
pkg_name |
Character. Site title shown in the viewer header. |
group_by |
Passed to |
Path to viewer.html invisibly.
Writes wasm_analytics.html into cfg$site_path using
inst/templates/wasm_analytics.html. All pipeline data is embedded
directly so the file opens as file:// with no server required.
generate_wasm_viewer(analytics_data, cfg, pkg_name = "targets docs")
analytics_data |
A list with |
cfg |
A site config list. |
pkg_name |
Character. Project title. |
Path to wasm_analytics.html invisibly.
Nothing is written to disk. The result can be embedded directly into a vignette string, printed, or passed to any downstream function.
get_fn_docs(fn_name, file)
fn_name |
Character. Function name (without |
file |
Character. Path to the |
A markdown string, or NULL (with a warning) if not found.
Recursively retrieves both upstream and downstream dependencies of a target with independently controlled depths, and returns relevant edges.
get_target_network_dependencies(
target_name,
network_data,
max_depth_up = Inf,
max_depth_down = Inf,
visited_up = NULL,
visited_down = NULL
)
target_name |
Character. Name of the target to analyse. |
network_data |
List from |
max_depth_up |
Integer. Max depth for upstream traversal. Use |
max_depth_down |
Integer. Max depth for downstream traversal. |
visited_up, visited_down |
Internal recursion tracking vectors – leave
as |
A list with:
Character vector of upstream node names.
Character vector of downstream node names.
Tibble of from/to edges traversed.
network_data <- list(
vertices = data.frame(name = c("A", "B", "C"), type = "target"),
edges = data.frame(from = c("A", "B"), to = c("B", "C"))
)
res <- get_target_network_dependencies("B", network_data,
max_depth_up = 1, max_depth_down = 1)
print(res$edges)
#> from to
#> 1 A B
#> 2 B C
Reads analytics.html, replaces the placeholder tokens with live values,
and writes _session_analytics.html – the file served at
http://localhost:<port> by view_tardoc_db().
inject_quack_session(
cfg,
token,
quack_port,
has_faiss = FALSE,
llm_enabled = FALSE
)
cfg |
A site config list. |
token |
Quack authentication token. |
quack_port |
Port the Quack server is listening on. |
has_faiss |
Logical. Whether the FAISS index was built. |
llm_enabled |
Logical. Whether an LLM chat backend is available. |
Path to _session_analytics.html invisibly.
tar_manifest() and tar_network() only require _targets.R to exist –
they parse the pipeline definition without needing a store. tar_meta()
requires the store (i.e. the pipeline has been run at least once) and
provides run history: status, timestamps, and errors. If no store is found
meta is filled with NAs so all downstream functions still work.
load_targets_data(cfg, check_outdated = TRUE)
cfg |
A site config list produced by |
check_outdated |
Logical. Call |
A named list with:
Tibble of target metadata. Status/time columns are NA if
no store exists.
Character vector of stem/pattern target names.
List from targets::tar_network().
Tibble from targets::tar_manifest().
Logical. Whether a store was found.
Character vector of stale target names, or NULL when
the check was skipped or failed.
Tibble from targets::tar_progress() – what each target
did on the last run – or NULL without a store.
Generate Rd documentation from roxygen comments (whole directory)
moxygenise(codepath, manpath)
codepath |
Character. Path to directory containing R source files. |
manpath |
Character. Path to directory where |
Invisibly NULL.
Generate Rd documentation from a single R script
moxygenise_file(file, manpath)
file |
Character. Path to a single |
manpath |
Character. Path to directory where |
Invisibly NULL.
Summarise where a pipeline spends its time and space
pipeline_profile(targets_data, top = 10L)
targets_data |
Output of |
top |
Integer. How many targets to rank. |
A list with total_seconds, total_bytes, slowest, largest,
critical_path (names) and critical_seconds (their total). slowest
and largest are data frames of name and the measure, already ordered.
Read a note file, returning empty string if not found
read_note(name, type = c("targets", "functions"), cfg)
name |
Character. Target or function name. |
type |
One of |
cfg |
A site config list. |
Character string (possibly empty).
The home-page counterpart of read_note(): notes/index.md, which is
yours to write and is never overwritten. Returns the empty string when it
is missing or still only the stub's comments.
read_overview(cfg)
cfg |
A site config list. |
Character string (possibly empty).
Read the recorded run history
read_run_history(cfg)
cfg |
A site config list. |
A list of snapshots, oldest first; empty when there is no history file or it cannot be parsed.
Writes history.json in cfg$site_path: one entry per docs build, each
recording every target's status, build time, runtime and size. Snapshots
are only appended when something actually differs from the previous one, so
repeated builds of an unchanged pipeline do not pad the file.
record_run_snapshot(targets_data, cfg, max_runs = 50L)
targets_data |
Output of |
cfg |
A site config list. |
max_runs |
Integer. How many snapshots to keep; the oldest are dropped. |
The full history, invisibly: a list of snapshots, oldest first.
A grouping earns its place when it has a handful of groups, none of them swallowing the pipeline, and enough members per group to be worth collapsing. Everything else – one group of 400, or 400 groups of one – is a restatement of the flat list.
score_grouping(g, min_per_group = 3, max_share = 0.7)
g |
A character vector of group labels, one per target. |
min_per_group |
Numeric. Mean members per group below which the grouping is rejected. Six groups across seven targets is arithmetically well balanced and completely useless, which is what this catches. |
max_share |
Numeric. Largest share of the pipeline one group may hold. A 90/10 split is not a grouping, however good its other numbers look. |
A numeric score; -Inf when the grouping is unusable.
score_grouping(rep(c("a", "b", "c"), each = 5))
#> [1] 2.213147
score_grouping(rep("everything", 20)) # -Inf: one group is no grouping
#> [1] -Inf
score_grouping(as.character(1:20)) # -Inf: all singletons
#> [1] -Inf
Starts the DuckDB duckdb_mcp extension server, making tardoc.duckdb
queryable by any MCP-compatible LLM client. Also writes
tardoc/tardoc_mcp_config.json – add its contents to your Claude Desktop
configuration to make the pipeline database available as a persistent tool.
serve_tardoc_mcp(project_path = ".", site_dir = "tardoc", port = 8765)
project_path |
Path to the targets project root. |
site_dir |
Subfolder used in |
port |
MCP server port. Default |
Create all required output directories
setup_site_dirs(cfg)
cfg |
A site config list produced by |
cfg invisibly.
Tries each signal in turn and takes the first that clears the bar:
target_groups(
targets_data,
cfg = NULL,
method = c("auto", "declaration", "functions", "prefix", "depth", "none"),
min_targets = 15L,
min_score = 1.2
)
targets_data |
Output of |
cfg |
A site config list; needed for |
method |
One of |
min_targets |
Integer. Below this many targets |
min_score |
Numeric. The bar a signal must clear for |
declarationThe file each target is declared in. This is the
author's own structure – how they chose to split _targets.R – and so
is preferred whenever a project has more than one such file.
functionsThe source file of the functions a target calls.
prefixA common name prefix, e.g. ingest_01 and ingest_02.
depthBands of longest-path depth. A last resort: meaningful on a deep pipeline, arbitrary on a wide one.
A list with method, score, and groups – a named character
vector of group label per target name. groups is empty when no signal
produced a usable grouping.
Open the Tier 1 static viewer (file://, no dependencies)
view_tardoc(project_path = ".", site_dir = "tardoc")
project_path |
Path to the targets project root. |
site_dir |
Subfolder used in |
Starts a DuckDB Quack server (background process via callr) and a minimal
httpuv HTML server. The browser DuckDB WASM connects via Quack for all
queries. When llm_chat is provided, a /chat endpoint is exposed and the
Chat tab becomes active.
view_tardoc_db(
project_path = ".",
site_dir = "tardoc",
port = 9000,
quack_port = 9494,
llm_chat = NULL,
db_extensions = FALSE
)
project_path |
Path to the targets project root. |
site_dir |
Subfolder used in |
port |
Port for the HTML server. Default |
quack_port |
Port for the Quack DuckDB server. Default |
llm_chat |
An ellmer |
db_extensions |
Logical. Install community DuckDB extensions when
building |
Opens wasm_analytics.html directly in the browser. DuckDB WASM is loaded
from CDN; all pipeline data is embedded in the HTML. Provides full SQL /
dplyr queries, BM25 search, and lineage – no R process required after
document_targets() has run.
view_wasm_analytics(project_path = ".", site_dir = "tardoc")
project_path |
Path to the targets project root. |
site_dir |
Subfolder used in |