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

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

Transcript

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

   View Slide

2. 自己紹介
   とと
   @totokit4（Twitter）
   2021.9　hey入社
   のiOSエンジニア
   関西出身
   めっちゃ緊張してるので
   みんなリアクションしてね！
   #voicy_hey
   

   View Slide

3. お店のキャッシュレスを
   かんたんに
   クレジットカード決済も、電子マネー決済も、
   QR決済も、これひとつで。
   

   View Slide

4. iOS SDKのドキュメントを
   自動生成したい！！
   

   View Slide

5. 目次
   1
   2
   3
   4
   背景と目的
   まずは、Jazzy触ってみた
   次に、DocC触ってみた
   STORES 決済 での運用方法
   

   View Slide

6. ドキュメント自動生成ツールって何よ
   0
   

   View Slide

7. ドキュメント自動生成ツール
   プログラムコードの中に書いた
   ドキュメントコメント こんな関数があるよ！
   このクラスは
   こういう役割だよ！
   引数はこれ！
   戻り値はこうだよ〜
   プロパティとして
   これが公開されてるよ〜
   HTML
   Markdown
   

   View Slide

8. ドキュメント自動生成ツール
   と、いうのを
   Swiftのプログラミングコードで
   やってくれるのが
   

   View Slide

9. 背景と目的
   1
   あらためまして
   

   View Slide

10. 目的
    STORES 決済 SDK
    コア機能をSDKとして切り出して
    他社のPOSアプリにも提供しています
    

    View Slide

11. 目的
    STORES 決済 SDKを組み込む人向けに
    APIドキュメントを展開しています
    …… …… が！！！
    

    View Slide

12. 背景
    先日、
    Objective-CからSwift化が完了
    

    View Slide

13. 背景
    Objective-C版のSDK でドキュメント生成に使用していた
    doxygenがSwiftに対応しておらず、
    乗り換える必要がありました
    

    View Slide

14. 背景
    オープンソースとして歴史が長く、信頼のある Jazzy、
    最近発表された、何と言ってもApple純正！の DocC。
    候補はこの2つ！
    どっちにするか調査を開始しました
    

    View Slide

15. まずは、Jazzy触ってみた
    2
    

    View Slide

16. Jazzy
    ● Realmが提供している Swift / Objective-Cに対
    応しているドキュメント生成ツール
    ● 少なくとも2014年からオープンソースで開発され
    ている
    ● 公式資料は英語
    ○ 導入事例等の記事が日本語で上がっている
    ● Issueで質問を投げてみたら1日以内に返信がきた
    

    View Slide

17. Jazzy触ってみた
    ● コマンドを2つターミナルに叩くだけ
    ○ `gem install jazzy` でインストール
    ○ `jazzy` でドキュメント生成
    

    View Slide

18. できたもの
    

    View Slide

19. Jazzy触ってみた
    ● 各種設定は、コマンドオプションをつけるか
    ● jazzy.yamlを作成して設定を変更
    ○ jazzy.yamlを作ってしまえば、変更はほぼここにしか入らない
    つけられるオプションの数が
    すごく多い！
    細かく設定するならこっち
    操作は基本CUI
    導入事例が多いので
    ネットに情報が多い
    

    View Slide

20. Jazzy苦戦したこと
    1. 「jazzy」で検索すると“ジャズっぽい雰囲気をあらわす言葉。
    ”が出る
    ○ ちゃうねん。
    ○ 「jazzy swift」とかで検索しよう
    2. xcodebuild-argumentsの設定むずい！！
    ○ ターゲット、ビルドディレクトリ、アーキテクチャ等々複雑なプロジェクトだとなかなか上手くいかない
    ■ が、これはjazzyのせいではない
    ○ Xcodeの環境変数が使えず、右往左往
    3. オプションについては、README1ページを地道に読むしかない！
    ○ どれ使うねん。何があんねん。
    ○ 地道にドキュメントを読んで、自分のチームに必要な設定をつける
    ○ 公式ドキュメントの親切さレベルはDocCの方が勝つ……気がする
    

    View Slide

21. 次に、DocC触ってみた
    3
    

    View Slide

22. DocC
    ● Appleから2021年6月にWWDC21で発表
    ● 2021年10月にオープンソースになった
    ● Xcode 13以降で利用可能
    ● 公式ドキュメントは英語のみ
    ○ 技術書典で売っていた本で公式ドキュメン
    トにある情報をほぼ網羅した日本語本が
    売っていた
    Swift-DocCでドキュメントをつくる： Type D4 Lab
    

    View Slide

23. DocC触ってみた
    ● Xcodeで全て完結
    ○ 設定、ドキュメントの生成までXcodeぽちぽちで完結
    

    View Slide

24. できたもの
    

    View Slide

25. DocC触ってみた
    ● Xcodeでビルドするたびにドキュメントを生成するというような設定
    ができる
    ● 概念を説明したり、タスクを説明したりするための記事を追加できる
    ● フレームワークの使い方を説明するチュートリアルが作れる
    ● 追加する画像をライトモード用やダークモード用で設定できる
    とにかくXcodeとの互換性が最高
    操作はGUIでOK
    見た目がApple Developer
    Documentationライクだったりと
    おしゃんなApple風にこだわるなら
    こっち
    

    View Slide

26. DocC苦戦したこと
    1. ドキュメント、
    英語しかない。導入事例少ない。
    ○ 何となく分かったつもりやけど、合ってるか自信ないわ…
    ○ 出来ることを自分が網羅的に把握できたのか自信ないわ…
    ■ 後からSwift-DocCでドキュメントをつくる を見つけました
    2. GUIだから、どこからミスったのか全然分からない
    ○ なんか失敗したな、と思ったら1からやり直し
    3. Documentation.md、独自ルールを覚えねばならない
    ○ README的な役割かと思いきや、設定ファイル的なポジションも
    ○ この設定をするのにこのファイルのどこを触らなくちゃいけないのかということの把握が必要
    

    View Slide

27. STORES 決済 での運用方法
    4
    

    View Slide

28. 　　
    ©hey, Inc
    Jazzy DocC
    Objective-Cのドキュメント化 ○ ×
    privateな関数等のドキュメント化 ○ ×
    ドキュメント化するファイルを指定 ○ ×
    チュートリアル等の作成 × ○
    多言語対応 × ×
    

    View Slide

29. 採用したのは
    doxygenで出来ていた、多言語対応はどちらでも実現できず。
    

    View Slide

30. 採用したのは
    ● Jazzyだと出力する内容のコントロールが細かくできる
    ● Jazzyは SwiftのPublicになっているものでも
    `/// :nodoc:` コメントつけると出力されない
    ○ 社内で展開する分にはDocCでも良さそう
    Jazzyを採用
    

    View Slide

31. 実装と運用
    ● ワークフローが動いたらドキュメントをzipで吐き出す
    ● ドキュメントバージョンも
    勝手にアプリバージョンに合わせてほしい
    

    View Slide

32. 実装
    1. jazzy.yamlファイルを用意
    ○ ここではmodule_version指定以外の設定を定義する
    2. Gemfileにjazzyを追加
    3. Fastfileにバージョン取得とJazzyを動かす処理をするlaneを追加
    4. BitriseのStepに `bundle install`のスクリプトを追加
    5. 作ったlaneを動かすスクリプトを追加
    6. 出力したドキュメントをzip化
    

    View Slide

33. 運用
    SDKをリリース時に動くワークフローに組み込んでおけば
    バージョンアップのたびにドキュメントが
    CI上で生成！
    ドキュメントのアップロードまで自動化したいのですが
    それはまだ検討中。現状は手動です
    

    View Slide

34. できたもの
    できたドキュメントは
    無事、公開中！😉
    https://stores-payments-sdk.coiney.com/ios/
    

    View Slide

35. おしまい
    

    View Slide

36. 実装
    Create Apple's documentation
    Stepが用意されていたが、
    指定できるパラメータが少ないため
    使用しませんでした
    ● xcodebuild-argumentsの設定が細かく設定できない
    ● バージョン固定してしまう
    

    View Slide

37. `/// :nodoc:` コメントについて
    コメントをつけなくても、公開されているAPIは
    DocCでもJazzyでも、ドキュメントは生成されてしまう
    

    View Slide

38. `/// :nodoc:` コメント について
    ドキュメントが生成されなくなる!!
    

    View Slide

39. ダイアグラムスタイル
    テキスト テキスト
    テキス
    ト テキス
    ト
    テキスト
    テキス
    ト
    テキスト テキスト テキスト
    テキスト テキスト
    テキス
    ト テキス
    ト
    テキスト
    テキス
    ト
    テキスト テキスト テキスト
    テキスト テキスト
    テキス
    ト テキス
    ト
    テキスト
    テキス
    ト
    テキスト テキスト テキスト
    A. ライン
    B. ライトトーン
    C. ダークトーン
    コネクタ
    

    View Slide

40. スタンプ
    

    View Slide

41. スタンプ
    

    View Slide