この記事は何？
Swift DocCの仕組みを解説。
そして、DocCによるリッチかつインタラクティブなドキュメントを作成する。
Swiftを基礎から学ぶには
自著、工学社より発売中の「まるごと分かるSwiftプログラミング」をお勧めします。変数、関数、フロー制御構文、データ構造はもちろん、構造体からクロージャ、エクステンション、プロトコル、クロージャまでを基礎からわかりやすく解説しています。
また、Swiftプログラミングを基礎から動画で学びたい方には、Udemyコース「今日からはじめるプログラミング」をお勧めします。
実行環境
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）
- チュートリアルページ
- セクション
- ステップ
- ステップ...
- セクション
- ステップ...
- セクション
- チュートリアルページ
- セクション
- ステップ...
- セクション
- チュートリアルページ
- チャプター
- ...
- チャプター（Tutorial.tutorial）
Appleが提供しているチュートリアル
Appleは開発者にSwiftUIフレームワークを学んでもらうために、初心者向けのチュートリアルを提供している。
下は、目次ページの画像。
各チャプターが内包するセクションまでが表示されている。
チャプター画面はいくつかのセクションで構成される。
各セクションでは、学習者が行うべき作業をステップごとに解説できる。
独自のチュートリアルを作ってみる
ワークスペースを作成する
まず、ワークスペースを作成する
次に、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 を以下のように編集する。
# チュートリアルについて
このチュートリアル全体の要約文。
## Overview
チュートリアル全体について、説明する。
Xcodeのメニューバーで「Product > Build Documentation」を選択する。
すると、Developer Documentationウィンドウが表示される。
下の画像は、ナビゲータに追加されたチュートリアルのドキュメント。
リンクをクリックすると...
Documentation.md ファイルの内容が記事として表示される。
画像とサンプルコード
ドキュメントカタログに「チュートリアル全体で使用するリソース（画像や動画、コードなど）」を保管しておく。
- Resources フォルダ直下に Image フォルダと Source フォルダを作成する
- Code フォルダに samplecode_01.swift を用意しておく
- Image フォルダに sampleimage_01.png を用意しておく
目次ファイル
ドキュメントが問題なくビルドできることを確認できたら、カタログに目次ページとなるファイルを追加する。
以下の手続きで、ワークスペースに Tutorial Table of Contents.tutorial ファイルを作成できる。
- ワークスペースのナビゲータエリアで、コンテキストメニューから「New File...」を選択する
- 「Tutorial Table of Contents File」を選択して、「Next」ボタンをクリックする
- 保存場所に「ワークスペースのフォルダ」を選択する
- Group は「MyTutorial」を指定する
- 「Create」ボタンをクリックする
- ナビゲータエリアで、作成された Tutorial Table of Contents.tutorial を Documentation.md と同じディレクトリに移動しておく
@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... を同じ手続きで作成しておく。
@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 を選択する。
@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が表示される。
実際のチュートリアルがどのように表示されるかをプレビューしながら、編集作業を行える。
目次を構成する
ナビゲータエリアで 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")
}
}
ドキュメントをビルドする
Xcodeのメニューバーで「Product > Build Documentation」をクリックする。
ナビゲータエリアで、作成したチュートリアルが追加されていることを確認して、選択する。
アーカイブをエクスポートする
ナビゲータで「Export」ボタンをクリックすると、チュートリアル全体をアーカイブフィイルに保存できる。
エクスポートされた.doccarchive形式のファイルを開くと...
XcodeのDeveloper Documentationウィンドウが表示され、チュートリアルを利用できる。