Chapter 02無料公開

第1章 Swift-DocC

USAMI Kosuke
USAMI Kosuke
2022.01.31に更新

1.1 Swift-DocCとは

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

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

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

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を使う前提で書かれている箇所があります。

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

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

1.4 サンプルの確認

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

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

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

Package.swiftをXcodeで開く

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

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

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

ビルドされた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によってドキュメントがビルドされます。

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

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

コラム:フレームワークやパッケージ以外でのSwift-DocCの活用

Swift-DocCは、基本的にはフレームワークやパッケージに対してのドキュメント生成で活用できます。一方で、アプリ開発で活用することも考えられます。開発中のアプリのドキュメントをSwift-DocCで生成できるようにしておくと、メンテナンスが楽になりそうです。

本書の執筆時点(2022年1月)ではbeta版ですが、Xcode 13.3ではアプリターゲットに対してもドキュメントが生成できるようになりました。

Xcode 13.2までは、アプリターゲットに対してドキュメントをビルドしてもドキュメントは生成されません。そこで、アプリ開発プロジェクトをマルチモジュール構成にして、モジュール化した部分のドキュメントをSwift-DocCで生成する、という手法が考えられます。マルチモジュール構成は通常、設計上の問題を解決したりビルド上の問題を解決したりするために導入されることが多いです。しかし、ドキュメント作成にSwift-DocCが使いやすくなるというメリットも、案外考慮する価値がありそうです。

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

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

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

Build Settings

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

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

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

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

Exportメニュー

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

1.7 Webサイトでの公開

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

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

脚注
  1. xcodebuild docbuildコマンドでもドキュメントをビルドできますが、これもXcodeに同梱されているSwift-DocCが使われます。 ↩︎

  2. https://github.com/apple/swift-docc ↩︎