DocCで簡単にチュートリアルを作ろう

# はじめに
プログラミング言語の教科書を作成したり、コードの作成手順を説明したりと、チュートリアルを作りたくなる場面はよくあります。
しかし、**コードのどこを編集すればいいかわからない**という悩みが常に発生します。
そこで、DocCを使って分かりやすいチュートリアルを簡単に作ろう！という記事です。

# DocCとは？
https://developer.apple.com/jp/news/?id=xa4ak3qr

DocCは「Documentation Compiler」の略で、AppleのXcodeに統合されたドキュメント作成ツールです。swiftでドキュメントを書いていくことができます。

一番典型的なのが**SwiftUIのチュートリアル**でしょう。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/1a6a41dc-9701-1372-53ac-fc4056b4e9ca.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/9249323a-c7c4-50ac-a42d-5a7383945658.png)

DocCを使うことで、このような形式のドキュメントをすぐに作ることができます。

# 新しいチュートリアルの作成方法

## プロジェクトの作成

では、Xcodeでチュートリアルを作成していきましょう。

Xcodeを開き、`File > New > Package`を選択します。

![スクリーンショット 2024-12-06 9.27.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/c8b932e0-1f1c-b5ee-7210-bc38333a16ff.png)

`Library`を選択します。

![スクリーンショット 2024-12-06 9.32.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/9fb40690-a2aa-04c4-4fb7-0ef128533444.png)

`TestingSystem`は`None`で大丈夫です。

![スクリーンショット 2024-12-06 9.33.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/bfb02c7c-849c-fb4d-8622-44aad1d6b521.png)

名前と保存先を設定しましょう。

![スクリーンショット 2024-12-06 9.35.03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/a479f5ab-7dfc-6b0c-f4e3-63d883d53fdd.png)

以下の画面が表示されたら成功です！

![スクリーンショット 2024-12-06 9.36.08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/9188b6a2-80e2-5b24-f7da-e1e95900db59.png)

## チュートリアルフォルダの作成

`Source`を右クリックして`New File from Template...`を選択します。

![スクリーンショット 2024-12-06 9.38.08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/3fee44c3-4589-733e-7f28-bbf01852c48e.png)

`Documentation Catalog`を選択し、追加します。

![スクリーンショット 2024-12-06 9.38.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/37cbaf72-d613-941b-92c3-1e282dcbf106.png)

次に、作成された`Documentation`を右クリックし、`New File from Template...`を選択します。

![スクリーンショット 2024-12-06 9.40.59.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/ae7d87ff-e1ed-b33b-4e1f-b1894ac8b262.png)

`Tutorial Table of Contents File`を選択します。

![スクリーンショット 2024-12-06 9.41.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/58985bac-a44d-1eee-8e3c-138f622469f9.png)

これがチュートリアルの章、節をまとめた一番最初の画面を与えます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/1a6a41dc-9701-1372-53ac-fc4056b4e9ca.png)

最後に再び`Documentation`を右クリックし、`New File from Template...`を選択します。

![スクリーンショット 2024-12-06 9.44.09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/23d11bf6-aeeb-8920-01a7-8fd009dd4565.png)

`Tutorial File`を選択し、追加します。

![スクリーンショット 2024-12-06 9.44.16.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/38d286e2-f58c-a2be-b031-c71327fe4a83.png)

そして、`Documentation`を`MyLibrary`の中に移動します。

![スクリーンショット 2024-12-06 9.48.47.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/0e5b50c3-282c-fbd4-e35c-b8fbf8e3c8d7.png)

:::note warn
`Package.swift`で`MyLibrary`が参照されているため、`Documentation`を移動しないとビルドしても表示されません！
:::

最終的にこのような画面になっていれば成功です！

![スクリーンショット 2024-12-06 9.51.12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/9606be63-f707-f828-0c91-c3a703f61d05.png)

# Table of Contentsの書き方

まずは、章と節をまとめる`Table of Contents`を書きましょう。

```swift:Table of Contents
@Tutorials(name: "SwiftUIを学ぼう") {
    @Intro(title: "SwiftUIを学ぼう") {
        新しいフレームワークであるSwiftUIを学びましょう！
        
        @Image(source: <#file#>, alt: "<#accessible description#>")
    }
    
    @Chapter(name: "Xcodeをインストールしよう") {
        SwiftUIでの開発に用いるIDEであるXcodeをインストールしましょう。
        
        @Image(source: <#file#>, alt: "<#accessible description#>")
        
        @TutorialReference(tutorial: "doc:Tutorial")
    }
}
```

ここで、各節（チュートリアル）をまとめるのが以下の行です。

```swift
@TutorialReference(tutorial: "doc:Tutorial")
```

ここで、`doc:`の後に書かれているのが **チュートリアルファイルの名前** です。

# ビルド方法

`Product > Build Documentation`を選びます。

![スクリーンショット 2024-12-06 9.55.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/99c680be-1095-5b94-8fc7-c24599d16ba7.png)

すると、このようなドキュメント一覧のウィンドウが立ち上がります。

![スクリーンショット 2024-12-06 9.57.03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/aff88028-0ec5-423e-094b-779264b2b7c9.png)

# 節を作成しよう

各節（チュートリアル）はいくつかの`Section`からなり、各`Section`はいくつもの`Step`からなります。

それぞれのチュートリアルにはかかる時間を設定することができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/e8d43970-7066-8763-a9e7-a6d1dc096bae.png)

## 画像を追加しよう

ドラッグ&ドロップで`Resources`フォルダに画像を追加します。

![スクリーンショット 2024-12-06 10.04.39.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/66915d71-b14b-4e6c-d341-a238df0611e2.png)

次のようにして画像を表示することができます。

```swift
@Step {
    Xcodeでプロジェクトを作成しましょう
                
    @Image(source: "screenshot.png", alt: "screenshot")
}
```

![スクリーンショット 2024-12-06 10.06.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/17c5eb17-c9e6-ff01-1bd9-19bb24491dc0.png)

## コードを追加しよう

通常のやり方で`.swift`ファイルを作成できます。

![スクリーンショット 2024-12-06 10.06.50.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/4f9857ac-74e8-6fdc-0a1c-cf92418006db.png)

以下のようにしてコードを追加できます。

```swift
@Step {
    File.swiftを開きます。
                
    @Code(name: "File.swift", file: File1.swift)
}
```

![スクリーンショット 2024-12-06 10.10.48.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/1aaee3c7-46b0-b3a6-d21e-ab0525a34996.png)

## 差分を表示しよう

新しくswiftファイルを作成します。

![スクリーンショット 2024-12-06 10.11.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/2e7d9ae6-8b6f-7f81-67fd-8f4b4fd86179.png)

Stepを追加してみましょう。

```swift
@Step {
    変数を追加します。
                
    @Code(name: "File.swift", file: File2.swift)
}
```

**nameを同じにしておくことで、** 差分が表示されます。

![スクリーンショット 2024-12-06 10.13.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2823873/2fc2c24c-9707-92d8-edd4-909eb5439059.png)

# まとめ
DocCを使うことで簡単にチュートリアルが作成できました。
チュートリアルの公開については別の記事を参照してみてください！

https://zenn.dev/oka_yuuji/articles/fba91851ae4ed3