Zenn
📄

Swift DocCを使ってドキュメンテーションを公開する

に公開
Swift
docs
swiftdocc
tech

これはなに

業務でiOS SDKに携わる機会があり、利用者に使い方を理解してもらうために、Swift DocCを使ってドキュメントを用意し、それをGitHub Pagesで公開したのでその手順を共有するものです

成果物

こちらに公開してます

Documentationの作成

初めに簡単なModelを用意します

簡単なモデルの例
cat.swift
struct Cat: Codable, Equatable {
    let id: String
    let tags: [String]
    let createdAt: String
    let url: String
    let mimetype: String

    enum CodingKeys: String, CodingKey {
        case id
        case tags
        case createdAt = "created_at"
        case url
        case mimetype
    }
}

これにコメントを付けていきます。
DocCでは///でコメントします。下記のようにコメントしました。(複数行にまたがる場合、 /** で開始し、*/ で終了できます

/// 猫に関する情報を表すモデル。
///
/// `Cat` は猫のID、タグ、作成日時、画像URL、MIMEタイプなどの情報を保持します。
/// `Codable` に準拠しているため、JSONとのエンコード・デコードが可能です。
/// また、`Equatable` に準拠しているため、等価比較もできます。
///
/// - Note: JSONの `created_at` キーは Swift の `createdAt` プロパティにマッピングされます。
struct Cat: Codable, Equatable {

    /// 猫の一意な識別子。
    var id: String

    /// 猫に関連付けられたタグのリスト。
    var tags: [String]

    /// この猫の情報が作成された日時（文字列形式）。
    ///
    /// JSON上の `created_at` キーからデコードされます。
    var createdAt: String

    /// 猫の画像やリソースへのURL。
    var url: String

    /// 猫画像のMIMEタイプ（例: `"image/jpeg"` や `"image/png"`）。
    var  mimetype: String

    /// JSONとプロパティ間のマッピングを行うための `CodingKeys`。
    ///
    /// 特に `created_at` を `createdAt` にマッピングするために使用されます。
    enum CodingKeys: String, CodingKey {
        case id
        case tags
        case createdAt = "created_at"
        case url
        case mimetype
    }
}

この時点で、XCode → Project →　Build Documentation (Ctrl + Shift + ⌘　+ D)します

するとXCodeでこのようなドキュメントが表示されるようになります。

どこかで見覚えのあるドキュメントが生成されました 🎉

記法について

ドキュメントタイトルとOverView

下記の様に一行目の後に改行をいれることにより、３行目以降が補足的な説明になります。

/// 猫に関するビジネスロジックを定義するユースケースプロトコル。
///
/// `CatUseCase` は猫の情報を取得する機能を提供するインターフェースです。
/// 実装側では、データソース（API、ローカルDBなど）から猫の情報を非同期で取得する処理を記述します。
protocol CatUseCase {

ドキュメント化するとこのように見えます

また、-や Note:、Important:などでマークアップすることにより、リスト表示や注釈を表現できます。他にSeeAlso:などもあります

/// - 表示内容:
///   - `idle`: 初期状態を示すテキスト表示。
///   - `loading`: 読み込み中インジケーター（`ProgressView`）。
///   - `success`: 取得した猫の画像を表示（なければ "No cat"）。
///   - `error`: エラーメッセージを表示。
///
/// - Note: このビューは `ReduxCatViewState<CatActionDispatcher>` を外部から受け取ります。

/// - Note: このクラスは `@MainActor` 指定されており、UI スレッド上で安全に動作します。
/// - Important: ジェネリクス `D` は `ActionDispatcher` プロトコルに準拠し、
///   `D.ActionType` は `CatAction` に一致している必要があります。

パラメータ及び返り値

/// - Parameters:
///   - action: 現在処理する猫関連のアクション。
///   - state: 現在の状態（`CatStoreState`）。

- Parameters:で宣言して、インデントを挟んで引数を登録できます

/// - Returns: アクションに基づいて更新された新しい状態。

- Returns:で宣言します

以下のようにパラメータ及び返り値のセクションが表示されるようになります

また、CatStoreStateのように``で囲むことによってシンボルのドキュメントに遷移させることができるようになります。

補足

Documentation Catalogを作成して記事を作成することもできます。

完全なサンプルはGitHubにもあげてますのでそちらも合わせてご確認ください

Documentの配布

GitHubPagesに公開するにあたりやるべき作業は以下２つです

  • DocCArchiveの作成
  • DocCArchiveのHTML化

DocCArchiveの作成

以下のようなコマンドでアーカイブを作成します

    xcodebuild docbuild \
        -project "$project_name/$project_name.xcodeproj" \
        -scheme "$scheme_name" \
        -destination "generic/platform=iOS" \
        BUILD_LIBRARY_FOR_DISTRIBUTION=NO

xcodebuild は Xcode のビルドツールです。
docbuild は DocC（Appleのドキュメント生成システム）用のビルドコマンドで、.doccarchive を生成します。
-schemeで、ビルド対象の スキーム（scheme） を指定しています。
これはプロジェクト内で定義されているビルド構成単位です（例えば Debug, Release, or Custom Scheme）。
BUILD_LIBRARY_FOR_DISTRIBUTION=NO: こちらはバイナリ配布目的ではないということを示しています

ShellScript
#!/bin/bash

# Constants
PROJECT_NAME="ohaken-redux"
SCHEME_NAME="ohaken-redux"
BUILD_DIR="build"
DOCC_OUTPUT_DIR="$BUILD_DIR/Documentation"

# Clean and create build directory
clean_build_directory() {
    local project_name=$1
    local build_dir=$2

    echo "Cleaning build directory..."

    if [ ! -d "$build_dir" ]; then
        echo "Creating build directory: $build_dir"
        mkdir -p "$build_dir"
    fi

    local archive_path="$build_dir/$project_name.doccarchive"
    if [ -e "$archive_path" ]; then
        echo "Removing existing archive: $archive_path"
        rm -rf "$archive_path"
    fi
}

# Generate DocC documentation
generate_doccarchive() {
    local project_name=$1
    local scheme_name=$2
    local output_dir=$3

    echo "Generating DocC documentation for $project_name..."
    xcodebuild docbuild \
        -project "$project_name/$project_name.xcodeproj" \
        -scheme "$scheme_name" \
        -destination "generic/platform=iOS" \
        BUILD_LIBRARY_FOR_DISTRIBUTION=NO

    if [ $? -ne 0 ]; then
        echo "Error: DocC generation failed for $scheme_name."
        exit 1
    fi

    local doccarchive_path
    doccarchive_path=$(find ~/Library/Developer/Xcode/DerivedData -type d -name "$scheme_name.doccarchive" | head -n 1)
    if [ -d "$doccarchive_path" ]; then
        echo "Moving $doccarchive_path to $output_dir..."
        mv "$doccarchive_path" "$output_dir"
    else
        echo "Error: DocC archive not found for $scheme_name."
        exit 1
    fi
}

# Main script execution
clean_build_directory "$PROJECT_NAME" "$DOCC_OUTPUT_DIR"
generate_doccarchive "$PROJECT_NAME" "$SCHEME_NAME" "$DOCC_OUTPUT_DIR"

echo "✅ DocC documentation successfully generated and saved in $DOCC_OUTPUT_DIR."

これで以下のようにdoccarchiveを作成することができます。

DocCArchiveのHTML化

xcrun docc process-archive transform-for-static-hosting コマンドを使います。
指定した.doccarchiveを静的サイト用に変換します

 xcrun docc process-archive transform-for-static-hosting \
        "$archive_path" \
        --output-path "./docs/" \
        --hosting-base-path "$hosting_base_path

--hosting-base-path /my-library-docs と指定すると、
トップページは /my-library-docs/index.htmlとなり、相対リンクもそれを基準に生成されます。

GitHub Pagesのように、ルート以外のパスでホスティングする時に必須のオプションです。

こちらもshellを貼っておきます

ShellScript

#!/bin/bash

静的ホスティング用に変換する関数

process_doccarchive() {
local archive_path=$1
local hosting_base_path=$2

echo "Processing $archive_path -> ./docs/"
xcrun docc process-archive transform-for-static-hosting \
    "$archive_path" \
    --output-path "./docs/" \
    --hosting-base-path "$hosting_base_path"

}

Main

set -e

docsディレクトリをクリーンアップ

echo "Cleaning up ./docs directory..."
rm -rf ./docs
mkdir -p ./docs

process_doccarchive "./build/Documentation/ohaken-redux.doccarchive" "/ohaken-redux"

echo "All documentation processed successfully!"

Github Pagesの設定については簡単ですがキャプチャを貼っておきます。一旦これでmainブランチpushでGitHub Actionsが動くはずです。

まとめ

  • //のコメントではなく///にすることで簡単にドキュメントを公開することができます
  • プロパティなどの記載も簡潔でわかりやすく書くことができ、
  • xcodebuildやxcrunなどのコマンドを使うことでアーカイブを静的ページに変換することができます 🎉

完全なサンプルはGitHubにもあげてますのでそちらも合わせてご確認ください

Discussion