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

by totokit4

Slide 1

Slide 1 text

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

まずは、Jazzy触ってみた 2

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

できたもの

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

次に、DocC触ってみた 3

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

できたもの

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

STORES 決済での運用方法 4

Slide 28

Slide 28 text

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

おしまい

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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