今回は、自分が開発したライブラリのドキュメントを、swift-doccを使用してGitHub Pagesにデプロイするまでの過程をご紹介したいと思います。
最近、私は「swiftui-simplex-architecture」という新しいSwiftライブラリをリリースしました。これは、TCAのようなアーキテクチャのライブラリで、SwiftUIを使用したアプリ開発をよりシンプルで効率的に行うことを目指したものとなっています。
より詳しいAPIのドキュメントを公開したかったので、Appleが提供しているswift-doccを使用してドキュメントを生成し、GitHub Pagesを通じて公開することにしました。
実装
実装はめちゃくちゃ簡単でした。このようなステップで簡単に公開が可能です.
- GitHub Pagesの設定
- swift-docc-pluginを使用してローカルでドキュメントを生成
- GitHubへpush
GitHub Pagesの設定
まずはリポジトリのSettingsをクリックします。
次にPagesをクリックします。
設定をこのようにします。
このようにすることで、mainブランチにpushされたら自動でdocsディレクトリにある内容がdeployされます。
swift-docc-plugin
まずは、ドキュメントを生成したいライブラリのPackage.swiftにswift-docc-pluginを追加します。
let package = Package(
name: "swiftui-simplex-architecture",
platforms: [
...
],
products: [
...
],
dependencies: [
...
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.1.0"),
],
...
)
そして、コマンドを実行します。再度実行しやすいように、Makefileにこのように記述します。
.PHONY: docc
docc:
swift package --allow-writing-to-directory ./docs \
generate-documentation --target SimplexArchitecture \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path swiftui-simplex-architecture \
--output-path ./docs
--targetにはドキュメントを生成したいライブラリのターゲットを、
--hosting-base-pathにはリポジトリ名を、
--allow-writing-to-directoryと--output-pathには、docsディレクトリへのパスを指定します。
$ make docc
で実行し、差分をmainにpushします。
すると、
https://{ユーザー名}.github.io/{リポジトリ名}/documentation/{ターゲット名}/
こちらのURLにドキュメントがデプロイされます！！
今回私はswiftui-simplex-architectureリポジトリのターゲットがSimlexArchitectureをデプロイしたので、
https://ryu0118.github.io/swiftui-simplex-architecture/documentation/simplexarchitecture/
こちらのURLにデプロイされました🎉
DocCのローカルでのプレビュー
ローカルでプレビューすることも可能です。
.PHONY: docc-preview
docc-preview:
swift package --disable-sandbox preview-documentation --target {ターゲット名}
これを実行すると、
このようにローカルサーバーが起動し、
http://localhost:8080/documentation/simplexarchitecture
にアクセスすると、プレビューが見れます。
さいごに
swift-doccでドキュメントを生成してGithub Pagesにデプロイするのめんどくさいだろうな...と考えていましたが、
めちゃくちゃ簡単にできてよかったです。
まだドキュメントが貧弱なので、TCA並に強化していきたいです！