前提知識

前提知識として、Swift言語の基本はある程度知っているものとします。また、Xcodeの使いかたもある程度知っているものとします。

開発環境としてMacとXcodeを使います。Swift-DocCはMac以外でも使用可能ですが、本書では扱いません。Xcodeはバージョン13以降が必要です。

1.1　Swift-DocCとは

Swift-DocCはドキュメントコンパイラと呼ばれるツールで、Swiftフレームワークやパッケージのためのドキュメントを作成できます。作成されたドキュメントはXcodeで開いて見ることができます。また、Webサイト上にホストできて、Webブラウザで見ることができます。

Xcodeには標準フレームワークのドキュメントが付属しています。このドキュメントは、Xcodeのメニューから「Help」→「Developer Documentation」を実行すると表示できます。Xcodeを使っているアプリ開発者ならば何度も見たことがあるでしょう。

Swift-DocCを使うと、これと同様のドキュメントを、ユーザーが簡単に作成できます。

図1.1: Xcode付属のドキュメント

1.2　Swift-DocCを使う方法

Swift-DocCを使う方法は2通りあります。

ひとつは、Xcodeに同梱されているものを使う方法です。Xcode上でドキュメントをビルドするとき*1、デフォルトでは同梱されているSwift-DocCが使われます。

もうひとつは、doccコマンドを自分でインストールして使う方法です。Swift-DocCはオープンソースソフトウェアとして公開されています。GitHubのapple/swift-docc*2リポジトリにdoccコマンドのインストール方法が書かれています。この方法の場合はXcodeなしで使うことができ、Mac以外のプラットフォームでも動作させることができます。また、このdoccコマンドをXcodeから呼ぶような設定もできます。

本書では、前者のXcodeを使う方法でSwift-DocCを学んでいきます。後者のdoccコマンドを使う方法は紹介だけにとどめておきます。

1.3　学ぶための情報源

Swift-DocCの公式ドキュメントは2つあります。ほとんど同じ内容ですが、若干異なる部分もあります。

ひとつは、Xcodeに付属しているドキュメントです。このドキュメントは、Xcodeを使う前提で書かれている箇所があります。

• DocC | Apple Developer Documentation
  • https://developer.apple.com/documentation/DocC

もうひとつは、Swift.orgからリリースされているドキュメントです。このドキュメントは、doccコマンドを使う前提で書かれている箇所があります。

• DocC | Swift.org - Documentation
  • https://www.swift.org/documentation/docc/

また、doccコマンドについては、GitHubのapple/swift-doccリポジトリにも詳細な情報が書かれています。

1.4　サンプルの確認

Swift-DocCを使ったサンプルがAppleから提供されています。

• SlothCreator: Building DocC Documentation in Xcode | Apple Developer Documentation
  • https://developer.apple.com/documentation/xcode/slothcreator_building_docc_documentation_in_xcode

このサンプル、SlothCreatorを少し眺めてみましょう。

SlothCreatorはSwiftパッケージになっています。まず、Package.swiftファイルをXcodeで開きます。

図1.2: Package.swiftをXcodeで開く

Sourcesフォルダの中に拡張子.swiftファイルがいくつかあります。このSwiftソースコードには、ドキュメント用のコメントがいくつか書かれています。

また、SlothCreator.doccというフォルダがあります。この中には拡張子.mdファイルがいくつかあります。Markdown形式でドキュメントが書かれています。

Xcodeのメニューから「Product」→「Build Documentation」を実行すると、Swift-DocCによってドキュメントがビルドされます。ビルドできると、Developer Documentationのウィンドウに表示されます。

図1.3: ビルドされたSlothCreatorドキュメント

Swift-DocCがビルドできるドキュメントの種類は、APIリファレンスとチュートリアルがあります。それぞれについての詳細は、第2章「APIリファレンス」、第3章「APIリファレンスの拡張」、第4章「チュートリアル」で説明します。

1.5　実際に手を動かすための準備

単にサンプルを見るだけでなく、実際に自分で試してみたい場合もあるでしょう。そのためには、題材となるSwiftフレームワークやパッケージが必要になります。ここでは、比較的簡単に準備できるSwiftパッケージを作ってみましょう。

空のディレクトリで次のコマンドを実行すると、Swiftパッケージに必要なファイルが作成されます。--nameオプションでパッケージの名前を指定します。この指定を省略した場合は現在のディレクトリの名前がパッケージの名前になります。

$ swift package init --name MySlothCreator --type library
Creating library package: MySlothCreator
Creating Package.swift
Creating README.md
Creating .gitignore
Creating Sources/
Creating Sources/MySlothCreator/MySlothCreator.swift
Creating Tests/
Creating Tests/MySlothCreatorTests/
Creating Tests/MySlothCreatorTests/MySlothCreatorTests.swift

作成されたPackage.swiftファイルをXcodeで開きます。Xcodeのメニューから「Product」→「Build Documentation」を実行すると、Swift-DocCによってドキュメントがビルドされます。

図1.4: ビルドされたMySlothCreatorドキュメント

もちろん、まだ何もドキュメントを書いていないのでほとんど空っぽです。しかし、これでSwift-DocCを試すための環境としては十分でしょう。

Tips：Xcodeプロジェクトのビルド時にドキュメントもビルドする設定

Swift-DocCによってドキュメントをビルドするには、通常はXcodeのメニューから「Product」→「Build Documentation」を実行します。

実は、XcodeプロジェクトのBuild Settingsの設定で、プロジェクトのビルド時にドキュメントもビルドするようにできます。「Build Documentation during 'Build'」の項目をYesにすれば良いです。

図1.5: Build Settings

前述の「1.5 実際に手を動かすための準備」のようにSwiftパッケージをXcodeで開いている場合には、Build Settingsが設定できないため利用できません。しかし、Xcodeプロジェクトが存在する場合には便利な設定です。

1.6　作成したドキュメントの共有

生成したドキュメントは、エクスポートして別の人に渡すことができます。

Xcodeの「Developer Documentation」ウィンドウの左ペインで、フレームワークを選択して右クリックすると「Export」メニューが出てきます。

図1.6: Exportメニュー

これを実行すると.doccarchive拡張子を持つドキュメントアーカイブが作成され、ほかの人へ渡すことができます。ドキュメントアーカイブを受け取った人は、Xcodeで開くことができます。

1.7　Webサイトでの公開

生成したドキュメントは、Webサイトに公開できます。公開する方法として、次の2つを紹介しておきます。

• Swift-DocC-Render
  • https://github.com/apple/swift-docc-render
  • 公式で提供されている手段。Vue.jsで作られている。

• VaporDocC
  • https://github.com/JosephDuffy/VaporDocC
  • Vaporで作られている（サーバサイドSwift）。

また、本書の執筆時点（2022年1月）では開発中の機能ですが、次の方法も紹介しておきます。

• Swift-DocC Plugin
  • https://github.com/apple/swift-docc-plugin
  • Swift Package Managerのプラグイン。ドキュメントのWebサイト公開をサポートする機能がある。