【Swift】DocCを基本から学ぶ

# この記事は何？

Swift DocCの仕組みを解説。
そして、DocCによるリッチかつインタラクティブなドキュメントを作成する。

> Swiftを基礎から学ぶには
自著、工学社より発売中の「[まるごと分かるSwiftプログラミング](https://amzn.asia/d/7YPWJwl)」をお勧めします。変数、関数、フロー制御構文、データ構造はもちろん、構造体からクロージャ、エクステンション、プロトコル、クロージャまでを基礎からわかりやすく解説しています。
> また、Swiftプログラミングを基礎から動画で学びたい方には、Udemyコース「[今日からはじめるプログラミング](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwii1qTuj_2BAxV4hlYBHbj5BqEQFnoECBYQAQ&url=https%3A%2F%2Fwww.udemy.com%2Fcourse%2Fstart-programming-today%2F&usg=AOvVaw2vs4Sccq-bpfA4ZD2rCyNm&opi=89978449)」をお勧めします。

### 実行環境

Xcode 15.4
Swift 6
macOS Sonoma 14.5

## DocCとは

Xcodeに搭載されている、ドキュメントコンパイラ（Document Compiler）。
マークダウンによる表記を **ディレクティブ** で拡張したフォーマットを利用する。
コメントのような、プログラムのコードではない部分をビルドしてドキュメントを作成できる。
作成したドキュメントは「Xcodeのドキュメントビューワー」で表示できるほか、Github PagesなどのWEBサーバー上で公開することも可能。

DocCはSwiftパッケージ、フレームワーク、プロジェクトで使用できる。
作成できるドキュメントの種類は、以下の通り。

* APIリファレンス
* 解説記事
* チュートリアル

## DocCのキーファクター

DocCでインタラクティブなドキュメントを作成するには、以下のオブジェクトを使用することになる。

- Documentation Catalog
- Tutorial Table of Contents File
- Tutorial File

### Documentation Catarog 

チュートリアルで使用する画像やコードのファイルを格納しておく場所。
付随的に、ワークスペースに *Documentation.md* ファイルが追加される。
ここに *Image* フォルダや *Code* フォルダなどを作って、リソースを管理しておくと良い。

### Tutorial Table of Contents File（.tutorial）

チュートリアル全体のトップディレクトリであり、学習者に目次の画面を提供する。
目次は、いくつかのチャプターによって構成される。
チャプターには、チュートリアルページを含めることができる。

### Tutorial File（.tutorial）

Tutorial Fileは、チュートリアルの1ページ。
1ページのチュートリアルはイントロから始まって、いくつかのセクションが続く構成。
各セクションでは`@Step`ディレクティブを使って、学習者が行うべき具体的な作業を記述する。

## ディレクティブ

ディレクティブは、DocCが表現するリッチなドキュメントのUIコンポーネントを記述するための構文です。
主に、*.tutorial* ファイルで使用します。



## DocCのチュートリアル

チュートリアルは、以下ように構成される。

- 目次（Table of Contents File.tutorial）
    - チャプター（Tutorial.tutorial）
        - チュートリアルページ
            - セクション
                - ステップ
                - ステップ...
            - セクション
                - ステップ...
        - チュートリアルページ
            - セクション
                - ステップ...
    - チャプター
        - ...


### Appleが提供しているチュートリアル

Appleは開発者にSwiftUIフレームワークを学んでもらうために、[初心者向けのチュートリアル](https://developer.apple.com/tutorials/develop-in-swift)を提供している。

下は、目次ページの画像。
各チャプターが内包するセクションまでが表示されている。

![スクリーンショット 2024-07-07 14.29.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/893df62d-bef9-39c9-02ea-72a4b0242b62.png)
![スクリーンショット 2024-07-07 14.29.52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/e9865c14-7162-15f6-b8b4-e99500e452a2.png)
![スクリーンショット 2024-07-07 14.30.41.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/7cca08c3-8fcb-00f2-2b4c-97a441d3f441.png)

チャプター画面はいくつかのセクションで構成される。
各セクションでは、学習者が行うべき作業をステップごとに解説できる。

![スクリーンショット 2024-07-07 14.37.09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/97406d84-66ca-5f24-2c2d-e66e00b480bf.png)


![スクリーンショット 2024-07-07 14.36.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/a4922392-258e-e3d0-36cc-a09bd1854889.png)



## 独自のチュートリアルを作ってみる

#### ワークスペースを作成する

まず、ワークスペースを作成する
次に、Swiftパッケージをワークスペースに追加する。

- Xcodeのメニューバーから「File > New > File... > Package」を選択する
- 「Library」を選択して、「Next」ボタンをクリックする
- 名前は「MyTutorial」とする
- 保存場所に「ワークスペースのフォルダ」を選択する
- *Add to* は「ワークスペース名」を指定して、「Create」ボタンをクリックする

#### ドキュメントカタログ

ワークスペースの「Soruces > MyTutoral」直下に「Documentation Catalog」を追加する。
すると、*Documentation.dcc* フォルダが作成される。
ここには、*Resource* フォルダと *Documentation.md* ファイルが含まれている。

- ワークスペースのナビゲータエリアで、コンテキストメニューから「New File...」を選択する
- 「Documentation Catalog」を選択して、「Next」ボタンをクリックする
- 保存場所に「Soruce > MyTutorial」を指定して、「Create」ボタンをクリックする

##### ビルドのテスト

この時点で、ドキュメントのビルドが正しく行えるかをチェックしておく。

*Documentation.md* を以下のように編集する。

```markdown: Documentation.md
# チュートリアルについて

このチュートリアル全体の要約文。

## Overview

チュートリアル全体について、説明する。
```

Xcodeのメニューバーで「Product > Build Documentation」を選択する。
すると、Developer Documentationウィンドウが表示される。
下の画像は、ナビゲータに追加されたチュートリアルのドキュメント。

![スクリーンショット 2024-07-08 10.51.41.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/118418fd-e6f3-15c7-5bb0-28bca9354f8f.png)

リンクをクリックすると...

![スクリーンショット 2024-07-08 10.53.52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/49553fc4-f4e9-54ff-680f-fdb4dbe3ef10.png)

*Documentation.md* ファイルの内容が記事として表示される。

##### 画像とサンプルコード

ドキュメントカタログに「チュートリアル全体で使用するリソース（画像や動画、コードなど）」を保管しておく。

- *Resources* フォルダ直下に *Image* フォルダと *Source* フォルダを作成する
- *Code* フォルダに *samplecode_01.swift* を用意しておく
- *Image* フォルダに *sampleimage_01.png* を用意しておく

![スクリーンショット 2024-07-08 11.23.47.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/16d096a9-a5cb-d804-f9fb-45a3b7d6f409.png)

#### 目次ファイル

ドキュメントが問題なくビルドできることを確認できたら、カタログに目次ページとなるファイルを追加する。
以下の手続きで、ワークスペースに *Tutorial Table of Contents.tutorial* ファイルを作成できる。

- ワークスペースのナビゲータエリアで、コンテキストメニューから「New File...」を選択する
- 「Tutorial Table of Contents File」を選択して、「Next」ボタンをクリックする
- 保存場所に「ワークスペースのフォルダ」を選択する
- *Group* は「MyTutorial」を指定する
- 「Create」ボタンをクリックする
- ナビゲータエリアで、作成された *Tutorial Table of Contents.tutorial* を *Documentation.md* と同じディレクトリに移動しておく

```swift: 追加されたTutorial Table of Contents Fileの内容
@Tutorials(name: "<#text#>") {
    @Intro(title: "<#text#>") {
        <#text#>
        
        @Image(source: <#file#>, alt: "<#accessible description#>")
    }
    
    @Chapter(name: "<#text#>") {
        <#text#>
        
        @Image(source: <#file#>, alt: "<#accessible description#>")
        
        @TutorialReference(tutorial: "doc:<#tutorial name#>")
    }
}
```

#### チュートリアルのページ

次は、「チュートリアルのページ」になる *.tutorial* 形式のファイルを作成する。

- ワークスペースのナビゲータエリアで、コンテキストメニューから「New File...」を選択する
- 「Tutorial.tutorial File」を選択して、「Next」ボタンをクリックする
- 保存場所に「ワークスペースのフォルダ」を選択する
- ファイル名に「Chapter01.tutorial」と入力する
- *Group* は「MyTutorial」を指定する
- 「Create」ボタンをクリックする
- ナビゲータエリアで、作成された *Chater01.tutorial* を *Documentation.md* と同じディレクトリに移動しておく

この時点でワークスペースには、「チュートリアルページのファイル」が1つだけ追加されている。
必要に応じて、*Chapter_02.tutorial*、*Chapter_03...* を同じ手続きで作成しておく。

```Swift: Tutorial.tutorial Fileのテンプレート
@Tutorial(time: <#number#>) {
    @Intro(title: "<#text#>") {
        <#text#>
        
        @Image(source: <#file#>, alt: "<#accessible description#>")
    }
    
    @Section(title: "<#text#>") {
        @ContentAndMedia {
            <#text#>
            
            @Image(source: <#file#>, alt: "<#accessible description#>")
        }
        
        @Steps {
            @Step {
                <#text#>
                
                @Image(source: <#file#>, alt: "<#accessible description#>")
            }
            
            @Step {
                <#text#>
                
                @Code(name: "<#display name#>", file: <#filename.swift#>)
            }
        }
    }
}
```

### 最初のチャプターを編集する

ナビゲータエリアで *Chapter01.tutorial* を選択する。

```swift:Chapter01.tutorial
@Tutorial(time: 10) {
    @Intro(title: "チャプター01のタイトル") {
        イントロの本文では、このチャプター全体で行う作業の概要を説明する。        
    }
    
    @Section(title: "最初のセクションのタイトル") {
        @ContentAndMedia {
            このセクションで行う作業の概要を説明する。            
        }
        
        @Steps {
            @Step {
                学習者に、最初のステップで行うべき作業を指示する。
                
                @Image(source: sampleiamge_01, alt: "コンピュータの画面から飛び立つアマツバメ")
            }
            
            @Step {
                学習者に、次のステップで行うべき作業を指示する。
                
                @Code(name: "constants.swift", file: samplecode_01.swift)
            }
        }
    }
    
    @Section(title: "次のセクションのタイトル") {
        @ContentAndMedia {
            このセクションで行う作業の概要を説明する。            
        }
        
        @Steps {
            @Step {
                学習者に、次のステップで行うべき作業を指示する。
                
                @Code(name: "constants.swift", file: samplecode_01.swift)
            }
            
            @Step {
                学習者に、次のステップで行うべき作業を指示する。
                
                @Code(name: "constants.swift", file: samplecode_02.swift)
            }
        }
    }
}
```

> Xcodeメニューバーから「Editor > Asisstant」を選択すると、エディタエリア右側にDocumentation Previewが表示される。
実際のチュートリアルがどのように表示されるかをプレビューしながら、編集作業を行える。

![スクリーンショット 2024-07-07 22.38.51.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/2c1c51a5-ca0a-bd20-9c40-bb3e9ebcd505.png)

### 目次を構成する

ナビゲータエリアで *Tutorial Table of Contents.tutorial* を選択する。

```swift: Tutorial Table of Contents.tutorial
@Tutorials(name: "チュートリアル全体のタイトル") {
    @Intro(title: "チュートリアル全体のタイトル") {
        チュートリアル全体と通して、学習者はどんなことを学び習得するか
    }
    
    @Chapter(name: "最初のチャプターのタイトル") {
        このチャプターについて、概要を説明する
        
        @Image(source: image_sample, alt: "コンピュータの画面から飛び立つアマツバメ")
        @TutorialReference(tutorial: "doc:Chapter01")
    }
    
    @Chapter(name: "次のチャプターのタイトル") {
        このチャプターについて、概要を説明する
        
        @Image(source: sampleimage_01, alt: "コンピュータの画面から飛び立つアマツバメ")
        @TutorialReference(tutorial: "doc:Chapter02")
    }
}
```

![スクリーンショット 2024-07-07 22.48.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/bb8e9c24-b0bb-8536-8637-a3a1d4a64413.png)

### ドキュメントをビルドする

Xcodeのメニューバーで「Product > Build Documentation」をクリックする。
ナビゲータエリアで、作成したチュートリアルが追加されていることを確認して、選択する。

![スクリーンショット 2024-07-08 11.29.46.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/a484efa0-83f6-e566-9ab4-afb0ff4bd1a2.png)
![スクリーンショット 2024-07-08 11.30.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/10a3c4b2-c762-1d09-0e30-ac3fc122da30.png)
![スクリーンショット 2024-07-08 11.31.06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/e80f0aa4-5b70-df64-81a4-2176ee6e016f.png)

### アーカイブをエクスポートする

ナビゲータで「Export」ボタンをクリックすると、チュートリアル全体をアーカイブフィイルに保存できる。

![スクリーンショット 2024-07-08 11.34.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/c6450d90-50b6-c315-c812-c30f78f768b6.png)

エクスポートされた.doccarchive形式のファイルを開くと...

![スクリーンショット 2024-07-08 11.37.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/70476/76586972-7fd8-9752-1f0f-7bce1ec36ff6.png)

XcodeのDeveloper Documentationウィンドウが表示され、チュートリアルを利用できる。