tomevault-io ドキュメント一括最新化
機能の実装が完了した後、関連するすべてのドキュメントを最新の状態に更新する。
以下の3つのドキュメントカテゴリを順番に更新する:
- 開発ドキュメント（設計書・実装計画書・API比較表）
- README.md
- チュートリアル
Phase 1: 変更内容の把握（共通）
git diff HEAD~5 --name-only
git log --oneline -10
変更されたソースファイルから、どの機能が実装・変更されたかを特定する。
Phase 2: 開発ドキュメントの更新
対象ドキュメント
- 設計書 (
docs/design/<feature>.md) - API設計、型定義、Streamlit比較 - 実装計画書 (
docs/impl/<feature>.md) - イテレーション計画、ファイル構成 - API比較表 (
docs/streamlit-api-comparison.md) - 実装状況の✅/❌を更新 - 技術ブログ (
docs/tech-blog-*.md) - 必要に応じて新規作成
Step 2-1: 設計書の更新 (docs/design/)
該当する設計書が存在する場合、以下を更新:
- 実装ステータス: 冒頭のステータスブロックを更新
> **✅ 実装完了** (YYYY-MM-DD) > > 実装内容の簡潔な説明 - API仕様: 実装に合わせて型定義やパラメータを修正
- Streamlitとの比較表: 実装済み項目を更新
該当する設計書が存在しない場合、既存の設計書（例: docs/design/cache-api.md）のフォーマットに従って新規作成:
# <機能名> 設計書
## 実装ステータス
> **✅ 実装完了** (YYYY-MM-DD)
> 実装内容の説明
## 1. 概要
### 1.1 目的
### 1.2 スコープ
### 1.3 設計原則
## 2. API仕様
## 3. 実装詳細
Step 2-2: 実装計画書の更新 (docs/impl/)
該当する実装計画書が存在する場合:
- 実装ステータス: 完了済みフェーズを更新
- イテレーション完了状況: 各フェーズの✅を追記
- ファイル構成: 実際に作成されたファイルと一致させる
Step 2-3: API比較表の更新 (docs/streamlit-api-comparison.md)
新しくAPIが実装された場合:
- 該当行の状況を
❌→✅に変更 kantan-uiカラムにkt.<api_name>を記入- 優先度・難易度カラムを
-に変更 - 備考に
実装済みを追記
Phase 3: README.md の更新
対象ファイル
README.md(英語)
README.md のセクション構成
現在のREADMEは以下の構造を持つ。更新箇所を特定して必要なセクションのみ更新する:
- Features - 主要機能のバレットリスト
- Quick Start - インストール・起動手順
- Usage - 基本的なコード例
- API Reference - 各APIカテゴリのリファレンス
- Output API / Streaming API / Alert API / Feedback API
- Data Display / Page Config / Widget API / Media API
- Layout API / Form API / Chat API / Empty Placeholder API
- Cache API / Session State
- How It Works - アーキテクチャ説明
- Development - npm scripts
- License
Step 3-1: 新機能の追加
新しいAPIやウィジェットが実装された場合:
- Features セクション: 必要であれば新しい特徴を追加
- API Reference セクション: 該当するカテゴリに新APIを追加
APIリファレンスの記述フォーマット（既存パターンに従う）:
### API名
```typescript
kt.api_name(param1: Type1, param2?: Type2): ReturnType
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| param1 | `Type1` | - | 説明 |
| param2 | `Type2` | `default` | 説明 |
```typescript
// Usage example
kt.api_name("value");
```
Step 3-2: 既存APIの変更
APIのシグネチャやパラメータが変更された場合:
- 型定義をソースコード (
src/kt/) と一致させる - パラメータテーブルを更新する
- コード例が動作することを確認する
Step 3-3: コード例の検証
README内のコード例が最新のAPIで動作するか確認:
src/index.tsのエクスポートと一致しているか- 型定義が正しいか
- import文が正しいか（
kantan-uiからのインポート）
Phase 4: チュートリアルの更新
対象ファイル
docs/TUTORIAL.md(日本語)
チュートリアルの構成
現在のチュートリアルは以下のセクションで構成されている:
- kantan-uiとは
- 環境構築
- Hello World
- ウィジェットの使い方（全ウィジェット）
- データ表示（table, metric）
- メディア（image, audio, video）
- レイアウト（tabs, columns, container, expander）
- チャットUI（chat_message, chat_container, chat_input）
- セッションステート（createTypedSessionState）
- キャッシュ（cache_data, cache_resource）
- ページ設定（set_page_config）
- 実践: カウンターアプリ
- 実践: TODOアプリ
- 実践: チャットアプリ
- 設定オプション
- 次のステップ
Step 4-1: 既存セクションの更新
既存のウィジェットやAPIが変更された場合:
- 該当セクションのコード例を最新APIに合わせて修正
- パラメータの説明を更新
- 新しいオプションがあれば追記
Step 4-2: 新しいセクションの追加
新しいAPIカテゴリが追加された場合、既存セクションのフォーマットに従って追加する。
ウィジェットの場合（セクション4に追加）
### <ウィジェット名>
`kt.<widget_name>()` は<説明>。
```typescript
const value = kt.<widget_name>("ラベル", options);
kt.write(`選択値: ${value}`);
```
**オプション:**
| パラメータ | 型 | デフォルト | 説明 |
|-----------|------|---------|------|
| label | `string` | - | ラベル |
| options | `object` | `{}` | 設定 |
新しいAPIカテゴリの場合
目次に新しい項目を追加し、セクションを作成する:
---
## <新セクション名>
<概要説明>
### 基本的な使い方
```typescript
import { createApp, kt } from "kantan-ui";
const script = () => {
// コード例
};
export default await createApp(script);
```
Step 4-3: 実践例の更新
実践セクション（カウンター、TODO、チャット）に新機能を活用した例を追加できる場合は更新する。ただし、既存の動作例を壊さないよう注意する。
Step 4-4: 目次の更新
セクションを追加・削除した場合、冒頭の目次を更新する。
Phase 5: 一貫性チェック（全体）
すべてのドキュメントを更新した後、以下を確認:
src/kt/index.tsでエクスポートされている全APIがREADMEに記載されているか- パラメータのデフォルト値がソースコードと一致しているか
- 型名がソースコードの型定義と一致しているか
- 設計書と実装計画書のステータスが矛盾していないか
- ドキュメント内の日付が正しいこと
- ファイルパスの参照が実際のコードと一致すること
記述ルール
README.mdは英語で記述するdocs/TUTORIAL.mdと開発ドキュメントは日本語で記述する- コード例は TypeScript で記述する
- 各APIにはパラメータテーブルと使用例を含める
- 既存のマークダウンスタイル・インデントを維持する
- チュートリアルは初心者が理解できるよう段階的に説明する（丁寧語「です・ます」調）
- コード例は完全に動作するものにする（断片的なコードを避ける）
- 不要になった設計書は
docs/archive/に移動する
Converted and distributed by TomeVault — claim your Tome and manage your conversions.