📚

DocC の成果物を Web ブラウザで簡単に閲覧する方法

2021/06/12に公開

Swift

tl;dr

Apple が作った新しいドキュメンテーションツール DocC の成果物を Web にホストしてブラウザでみる Vapor Middleware & Docker Image があったのでご紹介です。

DocC について

WWDC21 で Apple が Xcode 13 に新しいドキュメンテーションツールを DocC 搭載してきました。

DocC は Documentation Compiler という意味のようです。

DocC によって生成されたドキュメントは拡張子 doccarchive というパッケージに格納されます。 doccarchive は Xcode の Developer Documentation window で閲覧できるのはもちろん Web にホストして閲覧することもできます。（内部では Vue.js が使われているそうです）

Web 上にホストするためには

doccarchive に内包されているフォルダ構造に合わせて適切にルーティング設定をしてあげないといけないようです。この辺りは僕は知識が無くよく分かっていません。

誰か簡単にブラウザで見れるようにしてないかな？って思っていたら案の定さっそく対応しているリポジトリを発見しました。

Vapor の Middleware として実装されているので既存の Vapor で構築したサーバがあれば簡単にホストできます。

そして何よりもうれしいのは Docker イメージを提供してくれているので Docker 環境があればサクッと試すことが出来ます。

使ってみる

今回はセッションでも題材として使われていたこちらのサンプルコードで生成した doccarchive を利用します。

SlothCreator: Building DocC Documentation in Xcode | Apple Developer Documentation

doccarchive の準備です。

サンプルコードに入っている Package.swift を Xcode 13 で開く
メニューバーの Product メニューから Build Documentation を実行
ビルドが成功したら Developer Documentation window が勝手に開く
左カラムのなかに "SlothCreator" というフレームワークがあるので名前を右クリック
Export メニューを実行
エクスポート先としてここではデスクトップを指定。

エクスポートが完了したら以下のコマンドを実行します。（事前に Docker はインストールしておいてください）

docker run -p 8080:8080 -e REDIRECT_MISSING_TRAILING_SLASH=TRUE -e REDIRECT_ROOT=documentation/ -v ~/Desktop/SlothCreator.doccarchive:/docs ghcr.io/josephduffy/vapordocc

[ NOTICE ] Server starting on http://0.0.0.0:8080

というログが表示されたら http://localhost:8080/documentation/ にブラウザでアクセスします。

ナマケモノのかわいい絵が入ったドキュメントが表示されたら成功です。

Tips

先ほど紹介したコマンドでは2つの環境変数を設定しています。

REDIRECT_MISSING_TRAILING_SLASH=TRUE
REDIRECT_ROOT=documentation

REDIRECT_MISSING_TRAILING_SLASH は、URL の末尾に "/" が点いていない場合に自動的に "/" 付きの URL にリダイレクトするかどうかの設定です。デフォルトでは無効化されています。無効化されている状態で http://localhost:8080/documentation にアクセスしてもドキュメントは表示されずエラー画面が表示されます。個人的には有効にした方が "/" の付け忘れのせいでドキュメントが表示されないという問題が回避できるのでオススメです。

REDIRECT_ROOT はルートにアクセスした際にリダイレクトする先を指定できます。デフォルトでは設定されていないので http://localhost:8080 にアクセスした場合 JSON でエラーが表示されるだけです。こちらも先ほどの環境変数と同様に設定しておいた方が便利です。

蛇足ですが、僕が末尾に "/" を付けないといけないことを知らずに作者の方に助けを求めたところ、これら2つの環境変数を新たに付けてくれました。

まとめ

Docker ベースで提供されているため簡単に Web ブラウザ上で DocC で生成したドキュメントを閲覧出来るようになりました。

実際のユースケースを考えると GitHub Pages 上におくだけで簡単にドキュメントが見られるような仕組みの方が便利かと思います。これに関しては今年の後半くらいに DocC がオープンソース化することが発表されているので、オープンソース化後に Pages で簡単に見られるような仕組みが追加されることが期待できそうですね。