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

この記事は何？

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で終わることを確認してから、以下のテンプレートをコピーしてエディタに貼り付ける。
そして、プレースホルダコンテンツをカスタムコンテンツに置き換える。

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ディレクティブを使用して、関連するチャプターをグループ化する。
ボリュームには画像を含めることもできる。

@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ディレクティブで共有する。

@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.
        }
    }
}

簡単なチュートリアルの作成について、プロジェクトの始め方から終わりまでは、インタラクティブチュートリアルの作成の説明を参照。

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

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