はじめに
プログラミング言語の教科書を作成したり、コードの作成手順を説明したりと、チュートリアルを作りたくなる場面はよくあります。
しかし、コードのどこを編集すればいいかわからないという悩みが常に発生します。
そこで、DocCを使って分かりやすいチュートリアルを簡単に作ろう！という記事です。
DocCとは？
DocCは「Documentation Compiler」の略で、AppleのXcodeに統合されたドキュメント作成ツールです。swiftでドキュメントを書いていくことができます。
一番典型的なのがSwiftUIのチュートリアルでしょう。
DocCを使うことで、このような形式のドキュメントをすぐに作ることができます。
新しいチュートリアルの作成方法
プロジェクトの作成
では、Xcodeでチュートリアルを作成していきましょう。
Xcodeを開き、File > New > Packageを選択します。
Libraryを選択します。
TestingSystemはNoneで大丈夫です。
名前と保存先を設定しましょう。
以下の画面が表示されたら成功です！
チュートリアルフォルダの作成
Sourceを右クリックしてNew File from Template...を選択します。
Documentation Catalogを選択し、追加します。
次に、作成されたDocumentationを右クリックし、New File from Template...を選択します。
Tutorial Table of Contents Fileを選択します。
これがチュートリアルの章、節をまとめた一番最初の画面を与えます。
最後に再びDocumentationを右クリックし、New File from Template...を選択します。
Tutorial Fileを選択し、追加します。
そして、DocumentationをMyLibraryの中に移動します。
Package.swiftでMyLibraryが参照されているため、Documentationを移動しないとビルドしても表示されません！
最終的にこのような画面になっていれば成功です！
Table of Contentsの書き方
まずは、章と節をまとめる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")
}
}
ここで、各節（チュートリアル）をまとめるのが以下の行です。
@TutorialReference(tutorial: "doc:Tutorial")
ここで、doc:の後に書かれているのが チュートリアルファイルの名前 です。
ビルド方法
Product > Build Documentationを選びます。
すると、このようなドキュメント一覧のウィンドウが立ち上がります。
節を作成しよう
各節（チュートリアル）はいくつかのSectionからなり、各SectionはいくつものStepからなります。
それぞれのチュートリアルにはかかる時間を設定することができます。
画像を追加しよう
ドラッグ&ドロップでResourcesフォルダに画像を追加します。
次のようにして画像を表示することができます。
@Step {
Xcodeでプロジェクトを作成しましょう
@Image(source: "screenshot.png", alt: "screenshot")
}
コードを追加しよう
通常のやり方で.swiftファイルを作成できます。
以下のようにしてコードを追加できます。
@Step {
File.swiftを開きます。
@Code(name: "File.swift", file: File1.swift)
}
差分を表示しよう
新しくswiftファイルを作成します。
Stepを追加してみましょう。
@Step {
変数を追加します。
@Code(name: "File.swift", file: File2.swift)
}
nameを同じにしておくことで、 差分が表示されます。
まとめ
DocCを使うことで簡単にチュートリアルが作成できました。
チュートリアルの公開については別の記事を参照してみてください！