【DocC】TutorialsディレクティブのAPIリファレンスを読む

# この記事は何？

DocCドキュメントを作成するための[Tutorials](https://www.swift.org/documentation/docc/tutorials)について、Apple開発者向けドキュメントを読む。

## ディレクティブの階層

### Table of Contents File

- Tutorials（←これ）
    - Intro
        - Image
        - Video
    - Chapter
        - TutorialReference
        - Image
    - Volume
        - Chapter
            - TutorialReference
            - Image
        - Image
    - Resources
        - Documenttion
        - Downloads
        - Forums
        - SampleCode
        - Videos

### Tutorialページ

- Tutorial
    - XcodeRequirement
    - Intro
        - Image
        - Video
    - Section
        - ContentAndMedia
        - Steps
            - Step
                - Code
                    - Image
                - Image
                - Video
        - Stack
            - ContentAndMedia
                - Image
                - Video
    - Image
    - Assessments
        - MultipleChoice
            - Choice
                - Justification
                - Image

### Ariticle（解説記事）

- Article
    - Intro
        - Image
        - Video
    - ContentAndMedia
        - Image
        - Video
    - Stack
        - ContentAndMedia
            - Image
            - Video
        - Image
    - Assesments
        - MultipleChoice
            - Choice
                - Justification
                - Image

## Tutorialsディレクティブとは

読者をナビゲートするために、チュートリアルの目次ページを表示する。

### パラメータ

- name
チュートリアルの名前であり、必ず指定すること。通常、文書化しているSwiftフレームワークまたはパッケージの名前と一致する。

### 概要

目次リーダーが個々のチュートリアルページにアクセスするためのナビゲート構造を定義する。
*Tutorial table of content File* をドキュメントカタログに追加する。
ファイル名が.tutorialで終わることを確認してから、以下のテンプレートをコピーしてエディタに貼り付ける。
そして、プレースホルダコンテンツをカスタムコンテンツに置き換える。

```swift:Table of Contents File.tutorial
@Tutorials(name: "SlothCreator") {
    @Intro(title: "Meet SlothCreator") {
        Create, catalog, and care for sloths using SlothCreator. 
        Get started with SlothCreator by building the demo app _Slothy_.
        
        @Image(source: "slothcreator-intro.png", alt: "An illustration of 3 iPhones in portrait mode, displaying the UI of finding, creating, and taking care of a sloth in Slothy — the sample app that you build in this collection of tutorials.")
    }
    
    @Chapter(name: "SlothCreator Essentials") {
        @Image(source: "chapter1-slothcreatorEssentials.png", alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
        
        Create custom sloths and edit their attributes and powers using SlothCreator.
        
        @TutorialReference(tutorial: "doc:Creating-Custom-Sloths")
    }
}
```

nameパラメータは、チュートリアル全体の名前を指定する。
この名前は、ウェブ上では、チュートリアル全体とチュートリアルのURLに表示される。
次のIntroディレクティブは、テキストと画像を利用してチュートリアルを読者に紹介する。
そして、Chapterディレクティブでステップバイステップのページを参照する。
チャプターには画像を含めることもできる。

### 関連するチャプターをグループ化する

チュートリアルをレベル別に構成したい場合、Volumeディレクティブを使用して、関連するチャプターをグループ化する。
ボリュームには画像を含めることもできる。

```swift
@Tutorials(name: "SlothCreator") {
    @Intro(title: "Meet SlothCreator") {        
        ...
    }
    
    @Volume(name: "Getting Started") {
        Building sloths, caring for them, and interacting with them.
        
        @Chapter(name: "SlothCreator Essentials") {
            ...
        }
        
        @Chapter(name: "Basic Sloth Care") {
            ...
        }
        
        @Chapter(name: "Basic Sloth Interaction") {
            ...
        }
    }
    
    @Volume(name: "Climbing Higher") {
        Taking your sloths to the next level.
        
        @Chapter(name: "Powering Up") {
            ...
        }
        ...
    }    
   ...
}
```

### 継続的な学習リソースの提供

チュートリアルに関連リソースがある場合は、Resourceディレクティブで共有する。

```swift:
@Tutorials(name: "SlothCreator") {
    @Intro(title: "Meet SlothCreator") {
        ...
    }
    
    @Chapter(name: "SlothCreator Essentials") {
        ...
    }
    
    @Chapter(name: "Basic Sloth Care") {
        ...
    }
    
    @Chapter(name: "Basic Sloth Interaction") {
        ...
    }

    @Resources {
        Explore more resources for learning about sloths.

        @Videos(destination: "https://www.example.com/sloth-videos/") {
            Watch cute videos of sloths climbing, eating, and sleeping.

            - [Treetop Breakfast](https://www.example.com/sloth-videos/breakfast/)
            - [Slow Ascent](https://www.example.com/sloth-videos/climb/)
            - [Rest Time](https://www.example.com/sloth-videos/snoozing/)
        }

        @Downloads(destination: "https://www.example.com/images/sloth-wallpaper/") {
            Download the cutest sloth wallpaper for your iPhone, iPad, or Mac.
        }
    }
}
```

簡単なチュートリアルの作成について、プロジェクトの始め方から終わりまでは、[インタラクティブチュートリアルの作成](https://www.swift.org/documentation/docc/building-an-interactive-tutorial)の説明を参照。

### 内包できるディレクティブの一覧

- Intro(必須)
紹介テキストと、目次の上部に表示する画像またはビデオ
- Chapter（任意）
チュートリアル内のチャプター。
個々のチュートリアルページへのリンク。
少なくとも1つのチャプターが必要。
- Resources（任意）
関連リソース（ダウンロード、サンプルコード、ビデオなど）へのリンクを含むセクション。
- Volume（任意）
関連するチャプターのグループ。