Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
ど・ち・ら・にしようかな♪ JazzyとDocC
Search
totokit4
July 20, 2022
Programming
0
850
ど・ち・ら・にしようかな♪ JazzyとDocC
https://hey.connpass.com/event/249808/
totokit4
July 20, 2022
Tweet
Share
More Decks by totokit4
See All by totokit4
デブサミウーマン2023_totokit4
totokit4
5
1.3k
GitHub Copilotを使って ちょっと楽にUnitTestを書けるようになった
totokit4
2
2.9k
Other Decks in Programming
See All in Programming
Fragment Composition of GraphQL
quramy
7
1k
二郎系ラーメンのコールで学ぶ AST 解析
memory1994
PRO
7
1.7k
コーンフレークから始める モデリング会話入門
ogurotakayuki
0
370
FigmaとPHPで作る1ミリたりとも表示崩れしない最強の帳票印刷ソリューション
ttskch
43
19k
2 週間で Twitter Bot を作ってみた
contour_gara
0
540
AWS Application Composerで始める、 サーバーレスなデータ基盤構築 / 20240406-jawsug-hokuriku-shinkansen
kasacchiful
1
260
ADRを一年運用してみた/adr_after_a_year
hanhan1978
7
2.4k
Snowflakeで眠ったデータを起こそう!
estie
0
120
MetricKitで予期せぬ終了を検知する話 / Detect unexpected termination with MetricKit
nekowen
1
190
Rubyでたのしむクリエイティブコーディング/Enjoy Creative coding with Ruby
chobishiba
1
180
新宿ダンジョンを可視化してみた
satoshi7190
2
260
Polars入門
daikikatsuragawa
1
100
Featured
See All Featured
The Invisible Customer
myddelton
114
12k
Ruby is Unlike a Banana
tanoku
96
10k
Making Projects Easy
brettharned
108
5.5k
Put a Button on it: Removing Barriers to Going Fast.
kastner
58
3.1k
Building a Modern Day E-commerce SEO Strategy
aleyda
17
6.4k
How to name files
jennybc
65
93k
Side Projects
sachag
451
41k
The Cost Of JavaScript in 2023
addyosmani
16
3.9k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
227
16k
Atom: Resistance is Futile
akmur
259
25k
VelocityConf: Rendering Performance Case Studies
addyosmani
320
23k
Automating Front-end Workflow
addyosmani
1356
200k
Transcript
ど・ち・ら・にしようかな♪ JazzyとDocC
自己紹介 とと @totokit4(Twitter) 2021.9 hey入社 のiOSエンジニア 関西出身 めっちゃ緊張してるので みんなリアクションしてね! #voicy_hey
お店のキャッシュレスを かんたんに クレジットカード決済も、電子マネー決済も、 QR決済も、これひとつで。
iOS SDKのドキュメントを 自動生成したい!!
目次 1 2 3 4 背景と目的 まずは、Jazzy触ってみた 次に、DocC触ってみた STORES 決済
での運用方法
ドキュメント自動生成ツールって何よ 0
ドキュメント自動生成ツール プログラムコードの中に書いた ドキュメントコメント こんな関数があるよ! このクラスは こういう役割だよ! 引数はこれ! 戻り値はこうだよ〜 プロパティとして これが公開されてるよ〜
HTML Markdown
ドキュメント自動生成ツール と、いうのを Swiftのプログラミングコードで やってくれるのが
背景と目的 1 あらためまして
目的 STORES 決済 SDK コア機能をSDKとして切り出して 他社のPOSアプリにも提供しています
目的 STORES 決済 SDKを組み込む人向けに APIドキュメントを展開しています …… …… が!!!
背景 先日、 Objective-CからSwift化が完了
背景 Objective-C版のSDK でドキュメント生成に使用していた doxygenがSwiftに対応しておらず、 乗り換える必要がありました
背景 オープンソースとして歴史が長く、信頼のある Jazzy、 最近発表された、何と言ってもApple純正!の DocC。 候補はこの2つ! どっちにするか調査を開始しました
まずは、Jazzy触ってみた 2
Jazzy • Realmが提供している Swift / Objective-Cに対 応しているドキュメント生成ツール • 少なくとも2014年からオープンソースで開発され ている
• 公式資料は英語 ◦ 導入事例等の記事が日本語で上がっている • Issueで質問を投げてみたら1日以内に返信がきた
Jazzy触ってみた • コマンドを2つターミナルに叩くだけ ◦ `gem install jazzy` でインストール ◦ `jazzy`
でドキュメント生成
できたもの
Jazzy触ってみた • 各種設定は、コマンドオプションをつけるか • jazzy.yamlを作成して設定を変更 ◦ jazzy.yamlを作ってしまえば、変更はほぼここにしか入らない つけられるオプションの数が すごく多い! 細かく設定するならこっち
操作は基本CUI 導入事例が多いので ネットに情報が多い
Jazzy苦戦したこと 1. 「jazzy」で検索すると“ジャズっぽい雰囲気をあらわす言葉。 ”が出る ◦ ちゃうねん。 ◦ 「jazzy swift」とかで検索しよう 2.
xcodebuild-argumentsの設定むずい!! ◦ ターゲット、ビルドディレクトリ、アーキテクチャ等々複雑なプロジェクトだとなかなか上手くいかない ▪ が、これはjazzyのせいではない ◦ Xcodeの環境変数が使えず、右往左往 3. オプションについては、README1ページを地道に読むしかない! ◦ どれ使うねん。何があんねん。 ◦ 地道にドキュメントを読んで、自分のチームに必要な設定をつける ◦ 公式ドキュメントの親切さレベルはDocCの方が勝つ……気がする
次に、DocC触ってみた 3
DocC • Appleから2021年6月にWWDC21で発表 • 2021年10月にオープンソースになった • Xcode 13以降で利用可能 • 公式ドキュメントは英語のみ
◦ 技術書典で売っていた本で公式ドキュメン トにある情報をほぼ網羅した日本語本が 売っていた Swift-DocCでドキュメントをつくる: Type D4 Lab
DocC触ってみた • Xcodeで全て完結 ◦ 設定、ドキュメントの生成までXcodeぽちぽちで完結
できたもの
DocC触ってみた • Xcodeでビルドするたびにドキュメントを生成するというような設定 ができる • 概念を説明したり、タスクを説明したりするための記事を追加できる • フレームワークの使い方を説明するチュートリアルが作れる • 追加する画像をライトモード用やダークモード用で設定できる
とにかくXcodeとの互換性が最高 操作はGUIでOK 見た目がApple Developer Documentationライクだったりと おしゃんなApple風にこだわるなら こっち
DocC苦戦したこと 1. ドキュメント、 英語しかない。導入事例少ない。 ◦ 何となく分かったつもりやけど、合ってるか自信ないわ… ◦ 出来ることを自分が網羅的に把握できたのか自信ないわ… ▪ 後からSwift-DocCでドキュメントをつくる
を見つけました 2. GUIだから、どこからミスったのか全然分からない ◦ なんか失敗したな、と思ったら1からやり直し 3. Documentation.md、独自ルールを覚えねばならない ◦ README的な役割かと思いきや、設定ファイル的なポジションも ◦ この設定をするのにこのファイルのどこを触らなくちゃいけないのかということの把握が必要
STORES 決済 での運用方法 4
©hey, Inc Jazzy DocC Objective-Cのドキュメント化 ◦ × privateな関数等のドキュメント化 ◦
× ドキュメント化するファイルを指定 ◦ × チュートリアル等の作成 × ◦ 多言語対応 × ×
採用したのは doxygenで出来ていた、多言語対応はどちらでも実現できず。
採用したのは • Jazzyだと出力する内容のコントロールが細かくできる • Jazzyは SwiftのPublicになっているものでも `/// :nodoc:` コメントつけると出力されない ◦
社内で展開する分にはDocCでも良さそう Jazzyを採用
実装と運用 • ワークフローが動いたらドキュメントをzipで吐き出す • ドキュメントバージョンも 勝手にアプリバージョンに合わせてほしい
実装 1. jazzy.yamlファイルを用意 ◦ ここではmodule_version指定以外の設定を定義する 2. Gemfileにjazzyを追加 3. Fastfileにバージョン取得とJazzyを動かす処理をするlaneを追加 4.
BitriseのStepに `bundle install`のスクリプトを追加 5. 作ったlaneを動かすスクリプトを追加 6. 出力したドキュメントをzip化
運用 SDKをリリース時に動くワークフローに組み込んでおけば バージョンアップのたびにドキュメントが CI上で生成! ドキュメントのアップロードまで自動化したいのですが それはまだ検討中。現状は手動です
できたもの できたドキュメントは 無事、公開中!😉 https://stores-payments-sdk.coiney.com/ios/
おしまい
実装 Create Apple's documentation Stepが用意されていたが、 指定できるパラメータが少ないため 使用しませんでした • xcodebuild-argumentsの設定が細かく設定できない •
バージョン固定してしまう
`/// :nodoc:` コメントについて コメントをつけなくても、公開されているAPIは DocCでもJazzyでも、ドキュメントは生成されてしまう
`/// :nodoc:` コメント について ドキュメントが生成されなくなる!!
ダイアグラムスタイル テキスト テキスト テキス ト テキス ト テキスト テキス ト
テキスト テキスト テキスト テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト テキスト テキスト テキス ト テキス ト テキスト テキス ト テキスト テキスト テキスト A. ライン B. ライトトーン C. ダークトーン コネクタ
スタンプ
スタンプ