docs: revamp v2 docs — friendlier prose, navigation, and new guide pages by scarmuega · Pull Request #950 · txpipe/oura

scarmuega · 2026-06-15T13:35:42Z

What

A pass over the entire v2 docset (docs/v2/) to make the prose friendlier-but-efficient, lean on the Starlight components the site barely used, cut wasteful duplication, and improve navigation — without breaking any existing URLs (reordering is done via sidebar.order, no file moves).

Changes

Voice & structure

One consistent skeleton across every source/sink/filter page: what it is + when you'd use it, consistent (required)/(optional, default = X) field markup, gotchas surfaced as asides.
New section landing pages — sources/, sinks/, filters/, advanced/ — each with a "which one should I use?" comparison table.
Sinks clustered by category via sidebar.order: Console → Files → Messaging → Cloud → Database (no file moves, URLs stable).

Dedup

AWS and GCP credential chains (previously copy-pasted across 3 + 2 sink pages) now live once on the Sinks overview page; sink pages link to it. Fixed the incomplete GCP CloudFunction auth in passing.

Page length / on-topic

Split the 634-line Data Dictionary: the conceptual model + record-variant table stay; the Legacy-V1 event catalog moves to reference/legacy_v1_events.mdx.

Components (the site previously used one aside total)

Tabs on install methods, Kubernetes sidecar/standalone, cursor backends.
Steps on the daemon getting-started and the Kafka guide.
Asides for the four genuinely-gated integrations and for gotchas that were buried in prose; code-block title="daemon.toml" throughout.

New pages

How it works — the pipeline mental model, the site's first Mermaid dataflow diagram, the apply/undo/reset lifecycle, and the three ways to handle rollbacks.
Quick Start — copy-pasteable Steps: install → oura watch against a public relay (no node needed) → a minimal daemon.toml.
Troubleshooting — symptom → cause → fix entries, each linking to its canonical page.

Accuracy

Corrected stale "requires feature X" notes left wrong by the batteries-included change — only kafka/zeromq/mithril/wasm need a custom build; everything else ships by default.

Verification

Static checks pass: 55 pages, every internal /oura/v2/… link resolves, no dead relay hostnames (runnable examples use the live backbone.mainnet.cardanofoundation.org:3001), all code fences / asides / Tabs/Steps tags balanced with imports present, Mermaid fence well-formed.

Note

A live Astro build wasn't run here — the docs site lives in the sibling txpipe/docs repo and consumes Oura via a separate submodule checkout, so the real render (including the first-ever Mermaid block) is validated after this merges and the oura-v2 submodule is bumped.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

Added comprehensive quickstart guide, how-it-works, and troubleshooting documentation for users getting started
Reorganized filters, sinks, and sources documentation with clearer configuration examples and structured layouts
Enhanced installation guides across all platforms with improved instructions and tabbed navigation
New data reference documentation covering event schemas and configuration options

Bring the whole v2 docset up to a consistent, friendly-but-efficient voice and make it easier to navigate, without breaking any existing URLs. Highlights: - Consistent skeleton across every source/sink/filter page (what it is + when to use it; consistent required/optional field markup; gotchas as asides). - New section landing pages (sources/sinks/filters/advanced) with "which one should I use?" comparison tables. - Sinks clustered by category via sidebar.order (Console -> Files -> Messaging -> Cloud -> Database), no file moves. - Deduplicated the AWS/GCP credential chains onto the Sinks overview page. - Split the 634-line Data Dictionary: concept model stays, Legacy-V1 event catalog moves to its own reference page. - Components the site barely used: Tabs (install/k8s/cursor), Steps (daemon, kafka guide), asides for feature gating and gotchas, code-block titles. - New pages: How it works (pipeline model + first Mermaid diagram + rollback handling), Quick Start (watch -> minimal daemon.toml), Troubleshooting. - Accuracy: corrected stale "requires feature X" notes left wrong by the batteries-included change (only kafka/zeromq/mithril/wasm need a custom build). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-06-15T13:35:57Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 70f1fa06-6cfa-4e94-a974-bab5fcd5e8af

📥 Commits

Reviewing files that changed from the base of the PR and between 6c326dd and 703b7f5.

📒 Files selected for processing (55)

docs/v2/advanced/custom_network.mdx
docs/v2/advanced/finalize_options.mdx
docs/v2/advanced/index.mdx
docs/v2/advanced/intersect_options.mdx
docs/v2/advanced/pipeline_metrics.mdx
docs/v2/advanced/retry_policy.mdx
docs/v2/advanced/stateful_cursor.mdx
docs/v2/examples/index.mdx
docs/v2/filters/index.mdx
docs/v2/filters/into_json.mdx
docs/v2/filters/legacy_v1.mdx
docs/v2/filters/parse_cbor.mdx
docs/v2/filters/rollback_buffer.mdx
docs/v2/filters/select.mdx
docs/v2/filters/split_block.mdx
docs/v2/filters/wasm.mdx
docs/v2/filters/work_stats.mdx
docs/v2/guides/cardano_2_kafka.mdx
docs/v2/how_it_works.mdx
docs/v2/index.mdx
docs/v2/installation/binary_release.mdx
docs/v2/installation/docker.mdx
docs/v2/installation/from_source.mdx
docs/v2/installation/kubernetes.mdx
docs/v2/quickstart.mdx
docs/v2/reference/data_dictionary.mdx
docs/v2/reference/legacy_v1_events.mdx
docs/v2/sinks/aws_lambda.mdx
docs/v2/sinks/aws_s3.mdx
docs/v2/sinks/aws_sqs.mdx
docs/v2/sinks/elasticsearch.mdx
docs/v2/sinks/file_rotate.mdx
docs/v2/sinks/gcp_cloudfunction.mdx
docs/v2/sinks/gcp_pubsub.mdx
docs/v2/sinks/index.mdx
docs/v2/sinks/kafka.mdx
docs/v2/sinks/rabbitmq.mdx
docs/v2/sinks/redis.mdx
docs/v2/sinks/sql_db.mdx
docs/v2/sinks/stdout.mdx
docs/v2/sinks/terminal.mdx
docs/v2/sinks/webhook.mdx
docs/v2/sinks/zeromq.mdx
docs/v2/sources/hydra.mdx
docs/v2/sources/index.mdx
docs/v2/sources/mithril.mdx
docs/v2/sources/n2c.mdx
docs/v2/sources/n2n.mdx
docs/v2/sources/s3.mdx
docs/v2/sources/utxorpc.mdx
docs/v2/troubleshooting.mdx
docs/v2/usage/daemon.mdx
docs/v2/usage/dump.mdx
docs/v2/usage/library.mdx
docs/v2/usage/watch.mdx

📝 Walkthrough

Walkthrough

A comprehensive documentation refresh for Oura v2: adds new pages (quickstart, how_it_works, section indexes for sources/filters/sinks/advanced, troubleshooting, legacy_v1_events), rewrites all existing source/filter/sink/advanced/installation/usage pages into a consistent MDX style using Starlight Tabs, TabItem, Steps, and admonition components, and extracts the legacy V1 event catalog from data_dictionary.mdx into a dedicated reference page.

Changes

Oura v2 documentation refresh

Layer / File(s)	Summary
Landing, quickstart, and how-it-works pages `docs/v2/index.mdx`, `docs/v2/quickstart.mdx`, `docs/v2/how_it_works.mdx`	`index.mdx` rewritten with new intro, "New to Oura?" tip, and Windows caution callout. New `quickstart.mdx` adds a three-step `Steps` walkthrough (install, watch, daemon). New `how_it_works.mdx` describes the full pipeline, event action semantics, and record shape evolution.
Installation docs `docs/v2/installation/binary_release.mdx`, `docs/v2/installation/docker.mdx`, `docs/v2/installation/kubernetes.mdx`, `docs/v2/installation/from_source.mdx`	Binary release page converted to tabbed install methods (Shell, PowerShell, Homebrew, npm). Docker page gains a `caution` about the `latest` tag. Kubernetes page converted to Sidecar/Standalone `Tabs` with a replicas-at-1 caution. From-source link path corrected to `/oura/v2/...`.
CLI usage docs `docs/v2/usage/daemon.mdx`, `docs/v2/usage/watch.mdx`, `docs/v2/usage/dump.mdx`, `docs/v2/usage/library.mdx`	Daemon page rewritten with a Getting Started checklist and updated TOML skeleton with explicit `type` fields. Watch and dump pages each gain a `:::tip` callout clarifying `--magic` and `--since` options. Library page rewritten with `cargo add` and `Cargo.toml` code blocks.
Sources index and all source pages `docs/v2/sources/index.mdx`, `docs/v2/sources/n2n.mdx`, `docs/v2/sources/n2c.mdx`, `docs/v2/sources/utxorpc.mdx`, `docs/v2/sources/hydra.mdx`, `docs/v2/sources/mithril.mdx`, `docs/v2/sources/s3.mdx`	New `sources/index.mdx` with source-selection table. All source pages rewritten with consistent `daemon.toml`-titled snippets, required/optional field bullets, and relevant caution/tip callouts (e.g., Mithril snapshot tip, N2N custom-network tip).
Filters index and all filter pages `docs/v2/filters/index.mdx`, `docs/v2/filters/split_block.mdx`, `docs/v2/filters/parse_cbor.mdx`, `docs/v2/filters/select.mdx`, `docs/v2/filters/into_json.mdx`, `docs/v2/filters/legacy_v1.mdx`, `docs/v2/filters/rollback_buffer.mdx`, `docs/v2/filters/work_stats.mdx`, `docs/v2/filters/wasm.mdx`	New `filters/index.mdx` with pipeline overview and filter table. All filter pages rewritten with consistent structure; Select gains a "Metadata patterns" section; WasmPlugin and RollbackBuffer gain structured caution/why-it-helps sections; LegacyV1 gains explicit `include_*` option bullets.
Sinks index and all sink pages `docs/v2/sinks/index.mdx`, `docs/v2/sinks/stdout.mdx`, `docs/v2/sinks/terminal.mdx`, `docs/v2/sinks/file_rotate.mdx`, `docs/v2/sinks/webhook.mdx`, `docs/v2/sinks/kafka.mdx`, `docs/v2/sinks/zeromq.mdx`, `docs/v2/sinks/rabbitmq.mdx`, `docs/v2/sinks/redis.mdx`, `docs/v2/sinks/elasticsearch.mdx`, `docs/v2/sinks/sql_db.mdx`, `docs/v2/sinks/aws_`, `docs/v2/sinks/gcp_`	New `sinks/index.mdx` with sink-selection categories and AWS/GCP credential guidance. All sink pages rewritten with consistent structure; Kafka and ZeroMQ gain `:::caution[Requires a custom build]` blocks; AWS sinks consolidate credential docs into a shared note; Elasticsearch gains an explicit `sink.credentials` subsection.
Advanced config index and all advanced option pages `docs/v2/advanced/index.mdx`, `docs/v2/advanced/intersect_options.mdx`, `docs/v2/advanced/stateful_cursor.mdx`, `docs/v2/advanced/retry_policy.mdx`, `docs/v2/advanced/finalize_options.mdx`, `docs/v2/advanced/custom_network.mdx`, `docs/v2/advanced/pipeline_metrics.mdx`	New `advanced/index.mdx` linking all advanced blocks. Intersect options gains a Strategies section enumerating four modes. Stateful cursor converted to `Tabs`-based backend layout. Retry policy documents new default values and adds a backoff-schedule note. Custom network fixes a typo ("propoerties" → "properties").
Data dictionary refactor and legacy V1 events reference `docs/v2/reference/data_dictionary.mdx`, `docs/v2/reference/legacy_v1_events.mdx`	`data_dictionary.mdx` removes ~591 lines of inline legacy event catalog, adds `LegacyV1` to the record variants table, and links to the new `legacy_v1_events.mdx`. New page catalogs all 26 legacy event types with payload and Context field tables.
Guides, troubleshooting, and examples `docs/v2/guides/cardano_2_kafka.mdx`, `docs/v2/troubleshooting.mdx`, `docs/v2/examples/index.mdx`	Cardano-to-Kafka guide rewritten with `Steps` and a Kafka build caution. New `troubleshooting.mdx` covers seven common symptoms with TOML snippets and cross-links. Examples index narrowed to list only specific features requiring custom builds.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

txpipe/oura#908: Directly overlaps — both PRs modify docs/v2/installation/binary_release.mdx to consolidate install methods using Starlight Tabs/TabItem components.
txpipe/oura#943: Both PRs modify docs/v2/examples/index.mdx to restructure how example prerequisites and feature-flag requirements are presented.
txpipe/oura#937: Directly overlaps with docs/v2/advanced/finalize_options.mdx — both PRs reshape the stopping-condition bullets and max_block_quantity content in that page.

Suggested reviewers

paulobressan

Poem

🐇 Hoppity-hop through the docs I go,
Tabs and Steps now neatly in a row!
Legacy events get their own cozy page,
Caution blocks warn of the Kafka-build stage.
The rabbit now knows how to quickstart right —
oura watch by day, oura daemon by night! 🌙

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/v2-revamp

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

scarmuega requested a review from paulobressan as a code owner June 15, 2026 13:35

scarmuega merged commit d7b231a into main Jun 15, 2026
4 of 5 checks passed

scarmuega deleted the docs/v2-revamp branch June 15, 2026 13:37

scarmuega mentioned this pull request Jun 15, 2026

docs: fix MDX/Mermaid build errors in v2 docs #951

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: revamp v2 docs — friendlier prose, navigation, and new guide pages#950

docs: revamp v2 docs — friendlier prose, navigation, and new guide pages#950
scarmuega merged 1 commit into
mainfrom
docs/v2-revamp

scarmuega commented Jun 15, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 15, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

scarmuega commented Jun 15, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Changes

Verification

Summary by CodeRabbit

Documentation

Uh oh!

coderabbitai Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

scarmuega commented Jun 15, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 15, 2026 •

edited

Loading