ど・ち・ら・にしようかな♪ JazzyとDocC

https://hey.connpass.com/event/249808/

Transcript

1. ど・ち・ら・にしようかな♪ JazzyとDocC
2. 自己紹介 とと @totokit4（Twitter） 2021.9　hey入社 のiOSエンジニア 関西出身 めっちゃ緊張してるので みんなリアクションしてね！ #voicy_hey
3. お店のキャッシュレスを かんたんに クレジットカード決済も、電子マネー決済も、 QR決済も、これひとつで。
4. iOS SDKのドキュメントを 自動生成したい！！
5. 目次 1 2 3 4 背景と目的 まずは、Jazzy触ってみた 次に、DocC触ってみた STORES 決済 での運用方法
6. ドキュメント自動生成ツールって何よ 0
7. ドキュメント自動生成ツール プログラムコードの中に書いた ドキュメントコメント こんな関数があるよ！ このクラスは こういう役割だよ！ 引数はこれ！ 戻り値はこうだよ〜 プロパティとして これが公開されてるよ〜 HTML Markdown
8. ドキュメント自動生成ツール と、いうのを Swiftのプログラミングコードで やってくれるのが
9. 背景と目的 1 あらためまして
10. 目的 STORES 決済 SDK コア機能をSDKとして切り出して 他社のPOSアプリにも提供しています
11. 目的 STORES 決済 SDKを組み込む人向けに APIドキュメントを展開しています …… …… が！！！
12. 背景 先日、 Objective-CからSwift化が完了
13. 背景 Objective-C版のSDK でドキュメント生成に使用していた doxygenがSwiftに対応しておらず、 乗り換える必要がありました
14. 背景 オープンソースとして歴史が長く、信頼のある Jazzy、 最近発表された、何と言ってもApple純正！の DocC。 候補はこの2つ！ どっちにするか調査を開始しました
15. まずは、Jazzy触ってみた 2
16. Jazzy • Realmが提供している Swift / Objective-Cに対 応しているドキュメント生成ツール • 少なくとも2014年からオープンソースで開発され ている • 公式資料は英語 ◦ 導入事例等の記事が日本語で上がっている • Issueで質問を投げてみたら1日以内に返信がきた
17. Jazzy触ってみた • コマンドを2つターミナルに叩くだけ ◦ `gem install jazzy` でインストール ◦ `jazzy` でドキュメント生成
18. できたもの
19. Jazzy触ってみた • 各種設定は、コマンドオプションをつけるか • jazzy.yamlを作成して設定を変更 ◦ jazzy.yamlを作ってしまえば、変更はほぼここにしか入らない つけられるオプションの数が すごく多い！ 細かく設定するならこっち 操作は基本CUI 導入事例が多いので ネットに情報が多い
20. Jazzy苦戦したこと 1. 「jazzy」で検索すると“ジャズっぽい雰囲気をあらわす言葉。 ”が出る ◦ ちゃうねん。 ◦ 「jazzy swift」とかで検索しよう 2. xcodebuild-argumentsの設定むずい！！ ◦ ターゲット、ビルドディレクトリ、アーキテクチャ等々複雑なプロジェクトだとなかなか上手くいかない ▪ が、これはjazzyのせいではない ◦ Xcodeの環境変数が使えず、右往左往 3. オプションについては、README1ページを地道に読むしかない！ ◦ どれ使うねん。何があんねん。 ◦ 地道にドキュメントを読んで、自分のチームに必要な設定をつける ◦ 公式ドキュメントの親切さレベルはDocCの方が勝つ……気がする
21. 次に、DocC触ってみた 3
22. DocC • Appleから2021年6月にWWDC21で発表 • 2021年10月にオープンソースになった • Xcode 13以降で利用可能 • 公式ドキュメントは英語のみ ◦ 技術書典で売っていた本で公式ドキュメン トにある情報をほぼ網羅した日本語本が 売っていた Swift-DocCでドキュメントをつくる： Type D4 Lab
23. DocC触ってみた • Xcodeで全て完結 ◦ 設定、ドキュメントの生成までXcodeぽちぽちで完結
24. できたもの
25. DocC触ってみた • Xcodeでビルドするたびにドキュメントを生成するというような設定 ができる • 概念を説明したり、タスクを説明したりするための記事を追加できる • フレームワークの使い方を説明するチュートリアルが作れる • 追加する画像をライトモード用やダークモード用で設定できる とにかくXcodeとの互換性が最高 操作はGUIでOK 見た目がApple Developer Documentationライクだったりと おしゃんなApple風にこだわるなら こっち
26. DocC苦戦したこと 1. ドキュメント、 英語しかない。導入事例少ない。 ◦ 何となく分かったつもりやけど、合ってるか自信ないわ… ◦ 出来ることを自分が網羅的に把握できたのか自信ないわ… ▪ 後からSwift-DocCでドキュメントをつくる を見つけました 2. GUIだから、どこからミスったのか全然分からない ◦ なんか失敗したな、と思ったら1からやり直し 3. Documentation.md、独自ルールを覚えねばならない ◦ README的な役割かと思いきや、設定ファイル的なポジションも ◦ この設定をするのにこのファイルのどこを触らなくちゃいけないのかということの把握が必要
27. STORES 決済 での運用方法 4
28. 　　 ©hey, Inc Jazzy DocC Objective-Cのドキュメント化 ◦ × privateな関数等のドキュメント化 ◦ × ドキュメント化するファイルを指定 ◦ × チュートリアル等の作成 × ◦ 多言語対応 × ×
29. 採用したのは doxygenで出来ていた、多言語対応はどちらでも実現できず。
30. 採用したのは • Jazzyだと出力する内容のコントロールが細かくできる • Jazzyは SwiftのPublicになっているものでも `/// :nodoc:` コメントつけると出力されない ◦ 社内で展開する分にはDocCでも良さそう Jazzyを採用
31. 実装と運用 • ワークフローが動いたらドキュメントをzipで吐き出す • ドキュメントバージョンも 勝手にアプリバージョンに合わせてほしい
32. 実装 1. jazzy.yamlファイルを用意 ◦ ここではmodule_version指定以外の設定を定義する 2. Gemfileにjazzyを追加 3. Fastfileにバージョン取得とJazzyを動かす処理をするlaneを追加 4. BitriseのStepに `bundle install`のスクリプトを追加 5. 作ったlaneを動かすスクリプトを追加 6. 出力したドキュメントをzip化
33. 運用 SDKをリリース時に動くワークフローに組み込んでおけば バージョンアップのたびにドキュメントが CI上で生成！ ドキュメントのアップロードまで自動化したいのですが それはまだ検討中。現状は手動です
34. できたもの できたドキュメントは 無事、公開中！😉 https://stores-payments-sdk.coiney.com/ios/
35. おしまい
36. 実装 Create Apple's documentation Stepが用意されていたが、 指定できるパラメータが少ないため 使用しませんでした • xcodebuild-argumentsの設定が細かく設定できない • バージョン固定してしまう
37. `/// :nodoc:` コメントについて コメントをつけなくても、公開されているAPIは DocCでもJazzyでも、ドキュメントは生成されてしまう
38. `/// :nodoc:` コメント について ドキュメントが生成されなくなる!!
39. ダイアグラムスタイル テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト A. ライン B. ライトトーン C. ダークトーン コネクタ
40. スタンプ
41. スタンプ