documenting-warehouse-sources

データウェアハウスソースのドキュメント作成

ユーザー向けのソースドキュメントは posthog.com リポジトリ（このリポジトリではありません）の contents/docs/cdp/sources/<slug>.md に配置され、/docs/cdp/sources/<slug> と /docs/data-warehouse/sources/<slug> の両方で配信されます。このスキルは、すべてのソースドキュメントが 従うべき唯一の一貫した形式を定義します。新しいソースをリリースする際は /implementing-warehouse-sources と 併用してください。

posthog.com のチェックアウトが隣にあることを前提とします（例: ../posthog.com）。

ウェブサイトが自動的にレンダリングする2つの要素

接続フィールドやテーブル一覧を手書きする必要は ありません — どちらもサイトがビルド時に取得する public_source_configs API から提供され、MDX コンポーネントを介してドキュメントに反映されます:

• <SourceParameters /> は get_source_config.fields から接続/設定フォームのフィールドをレンダリングします。
• <SourceTables /> はソースの get_documented_tables() から サポートされているテーブル のリファレンス （テーブル名、説明、同期方法、増分フィールド、主キー）をレンダリングします。

<SourceTables /> にデータが入るのは、ソースがソースクラスで lists_tables_without_credentials = True を設定してオプトインした場合のみです（get_schemas が I/O を伴わない 静的な エンドポイントカタログを反復処理する場合にのみ有効 — /implementing-warehouse-sources を参照）。 それ以外の場合は、汎用的な「あなたのアカウントから検出されました」という注記がレンダリングされます。 テーブルが欠けている場合や説明が薄い場合は、ドキュメントではなくソースコードを修正してください （settings.py のエンドポイント + canonical_descriptions.py）。ドキュメントは API が返す内容を レンダリングするだけなので、コードが単一の信頼できる情報源であり続けます。

フロントマター

---
title: Linking <Source> as a source
sidebar: Docs
showTitle: true
availability: { free: full, selfServe: full, enterprise: full }
sourceId: <EnumValue> # MUST equal the ExternalDataSourceType value, e.g. ActiveCampaign, Stripe
beta: true # optional — only for beta sources
---

sourceId はドキュメントを API 設定（アイコン、フィールド、テーブル）にリンクするものです。これを間違えると、 ドキュメントは <SourceParameters /> / <SourceTables /> のデータなしでレンダリングされます。これは実際の ExternalDataSourceType の値（PascalCase、例: ActiveCampaign、Active Campaign ではない）でなければなりません。

標準テンプレート

---
title: Linking <Source> as a source
sidebar: Docs
showTitle: true
availability: { free: full, selfServe: full, enterprise: full }
sourceId: <EnumValue>
---

import SourceSetupIntro from "../_snippets/source-setup-intro.mdx"
import SyncModes from "../_snippets/sync-modes.mdx"
import TroubleshootingLink from "../_snippets/dw-troubleshooting-link.mdx"



One or two sentences: what this connector syncs and the typical use case.

## Prerequisites

Account tier / admin rights / API access the user needs before they can connect.

## Adding a data source

<SourceSetupIntro />

List the specific credentials this source needs and exactly where to get them (link to the provider's
dashboard). For sources with more than one auth method, use `###` subsections (mirror Stripe's
"Option 1 / Option 2").

## Sync modes

<SyncModes />

Add any source-specific recommendation here (e.g. "use webhooks for Stripe").

## Configuration

<SourceParameters />

## Supported tables

<SourceTables />

## Troubleshooting

Source-specific errors and fixes (optional but encouraged), then:

<TroubleshootingLink />

必須セクション（すべてのソース）

ステータスコールアウト（alpha/beta のみ） → はじめに → 前提条件 → データソースの追加 → 同期モード → 設定 → サポートされているテーブル → トラブルシューティング。

任意セクション（該当する場合）

Webhook（リアルタイム同期）、CDC（データベース）、カラム選択、行フィルター、受信 IP アドレス （<InboundIpAddresses />）、データ型の処理、既知の制限事項、ERD/リレーションシップ。リポジトリに すでにある参考実装: Stripe（SaaS + Webhook）、Postgres（データベース + CDC）、 ClickHouse（データベース）。ソースに必要のないセクションをでっち上げないでください。

共有スニペット

同じ文章を書き直す代わりに、これらを再利用してください（contents/docs/cdp/_snippets/ にあります）:

• source-setup-intro.mdx — 標準的な「データソースの追加」手順。
• sync-modes.mdx — 標準的な説明にリンクする同期モードの概要。
• alpha-release.mdx / beta-release.mdx — ステータスコールアウト（フロントマターで beta: true も設定します）。
• dw-troubleshooting-link.mdx — トラブルシューティング/サポートのフッター。
• inbound-ip-addresses.mdx — DB ソース用の IP 許可リストテーブル。
• feedback-questions.mdx — フィードバック/FAQ のフッター。

.md ソースドキュメントは MDX の import をサポートしているため（例: convex.md、mongodb.md）、 スニペットを使うために .mdx にリネームする必要はありません — ただし .mdx でも問題ありません。 CalloutBox、ProductScreenshot、SourceParameters、SourceTables はグローバルコンポーネントです — インポートは不要です。

docsUrl / slug ルール（404 を防ぎます）

ウェブサイトはソースの docsUrl（その最後の /docs/cdp/sources/<slug> セグメント）からドキュメントの slug を導出するため、次の 3 つが一致している必要があります。

1. ドキュメントのファイル名: <slug>.md。
2. get_source_config 内のソースの docsUrl: https://posthog.com/docs/cdp/sources/<slug>。
3. （暗黙的に）一覧のリンク — 現在は docsUrl から導出されるため、自動的に追随します。

複数単語の slug には kebab-case を使用してください（activecampaign ではなく active-campaign）。ドキュメントを作成または名前変更した後、この（posthog）リポジトリから監査を実行してください:

python manage.py audit_source_docs --docs-dir ../posthog.com/contents/docs/cdp/sources

これは、いずれかのソースの docsUrl が存在しないファイルを指している場合、またはいずれかのドキュメントの sourceId が実在するソースでない場合に失敗します。 公開済みのドキュメントの名前を変更する場合は、posthog.com/vercel.json に /docs/cdp/sources/* と /docs/data-warehouse/sources/* の両方に対する 301 も必要です。

チェックリスト

• フロントマターの sourceId が ExternalDataSourceType の値と完全に一致している
• はじめに、前提条件、データソースの追加、同期モード、設定、サポートされるテーブル、トラブルシューティング
• ステータススニペット + アルファ/ベータの場合は beta: true
• 独自の文章ではなく共有スニペットを使用している
• <SourceParameters /> と <SourceTables /> が存在する（フィールドやテーブル一覧を手書きしない）
• レンダリングされたテーブル一覧が空または乏しく、ソースが固定スキーマである場合は、そのコード（lists_tables_without_credentials、settings.py、canonical_descriptions.py）を充実させる — /implementing-warehouse-sources を参照
• ファイル名、docsUrl、slug がすべて一致している（kebab-case）
• audit_source_docs がパスする