# バッチ設計書 13-doc:site

## 概要

本ドキュメントは、CoffeeScriptプロジェクトにおける`doc:site`タスクの設計書です。このバッチは、CoffeeScript公式Webサイト用のドキュメントをビルドし、HTMLファイルとして出力するドキュメント生成ツールです。

### 本バッチの処理概要

このバッチは、`documentation/site/`配下のソースファイルを処理し、CoffeeScript公式サイトのHTMLドキュメントを生成します。Markdownファイルをパース・変換し、テンプレートエンジンで処理した後、最終的なHTMLを`docs/vX/`ディレクトリに出力します。

**業務上の目的・背景**：CoffeeScriptの公式ドキュメントは、言語仕様、使用方法、変更履歴などを開発者に提供するための重要なリソースです。このバッチを使用することで、Markdownで記述されたドキュメントソースから、スタイリングされたHTML形式のWebサイトを自動生成できます。リリース時や文書更新時に、一貫したフォーマットでドキュメントを公開するために不可欠なタスクです。

**バッチの実行タイミング**：手動実行、または`release`タスクの一部として実行されます。ドキュメントの更新後やリリース準備時に実行します。

**主要な処理内容**：
1. `documentation/site/index.html`テンプレートを読み込み
2. `documentation/sections/`配下のMarkdownファイルをパース
3. `documentation/examples/`配下のコードサンプルを処理
4. highlight.jsによる構文ハイライト適用
5. Underscore.jsテンプレートエンジンで変数展開
6. CoffeeScriptコードをJavaScriptにコンパイル・Babelで変換
7. 最終HTMLを`docs/vX/index.html`に出力
8. `docs/index.html`へのシンボリックリンクを作成

**前後の処理との関連**：`release`タスクから呼び出されることがあります。`build:browser`タスクでブラウザ用コンパイラがビルドされていることが望ましいです。

**影響範囲**：`docs/vX/`ディレクトリにHTMLファイルが生成されます。`docs/index.html`シンボリックリンクが更新されます。

## バッチ種別

ドキュメント生成 / Webサイトビルド

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時・ドキュメント更新時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動/releaseタスク |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.jsがインストールされていること |
| 依存パッケージ | `npm install`が完了していること |
| ドキュメントソース | documentation/site/配下にソースファイルが存在すること |

### 実行可否判定

- `documentation/site/index.html`が存在すること
- `documentation/sections/`ディレクトリが存在すること
- 必要なnpmパッケージ（highlight.js、markdown-it、underscore等）がインストールされていること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数なし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| documentation/site/index.html | HTML(テンプレート) | メインページテンプレート |
| documentation/sections/*.md | Markdown | ドキュメントセクション |
| documentation/sections/changelog/*.md | Markdown | 変更履歴 |
| documentation/examples/*.coffee | CoffeeScript | コード例 |
| documentation/site/code.coffee | CoffeeScript | コード例生成モジュール |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| docs/vX/index.html | HTML | 生成されたWebサイト |
| docs/index.html | シンボリックリンク | vX/index.htmlへのリンク |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | index.html |
| 出力先 | docs/vX/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. 定数・パス設定
   └─ indexFile、siteSourceFolder、sectionsSourceFolder等を設定
2. ヘルパー関数定義
   └─ releaseHeader、codeFor、htmlFor、includeScript、include関数を定義
3. Markdown-Itレンダラー設定
   └─ highlight.jsによる構文ハイライト設定
4. カスタムfenceレンダラー設定
   └─ codeFor()、releaseHeader()を含むコードブロックの処理
5. テンプレート処理
   └─ Underscore.jsテンプレートで変数展開
6. HTML出力
   └─ docs/vX/index.htmlに出力
7. シンボリックリンク作成
   └─ docs/index.html → vX/index.html
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[設定読み込み]
    B --> C[ヘルパー関数初期化]
    C --> D[Markdown-Itレンダラー設定]
    D --> E[index.htmlテンプレート読み込み]
    E --> F[Markdownセクション処理]
    F --> G[コード例処理]
    G --> H[テンプレート変数展開]
    H --> I[HTML出力]
    I --> J[シンボリックリンク作成]
    J --> K[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

該当なし（ファイルシステム操作のみ）

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル読み込みエラー | ソースファイルが存在しない | ファイルパスを確認 |
| - | テンプレートエラー | テンプレート構文エラー | テンプレートを修正 |
| - | シンボリックリンクエラー | リンク作成失敗 | 既存リンクを削除して再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

- シンボリックリンクエラーはtry-catchで捕捉され、処理は継続する
- ファイル読み込みエラー時は例外がスローされる

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十のMarkdownファイル |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

- 同時実行：可能だが推奨しない
- ロック仕様：なし

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 完了ログ | HTML出力完了時 | "compiled documentation/site/index.html → docs/vX/index.html" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- `majorVersion`変数によりCoffeeScriptのメジャーバージョンに応じた出力先が決定される
- highlight.jsによる構文ハイライトがサポートされている言語に対して適用される
- Babelによるトランスパイルとminifyが適用される（環境変数で制御可能）
- `<%= majorVersion %>`、`<%= fullVersion %>`等のプレースホルダーが自動展開される
