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
1.1k
ど・ち・ら・にしようかな♪ JazzyとDocC
https://hey.connpass.com/event/249808/
totokit4
July 20, 2022
Tweet
Share
More Decks by totokit4
See All by totokit4
re:Inventなんも分からんけどとりあえず全力で行く
totokit4
0
220
カンファレンスを全力で楽しむ技術
totokit4
0
190
デブサミウーマン2023_totokit4
totokit4
5
1.8k
GitHub Copilotを使って ちょっと楽にUnitTestを書けるようになった
totokit4
2
3.3k
Other Decks in Programming
See All in Programming
GitHub Actionsのキャッシュと手を挙げることの大切さとそれに必要なこと
satoshi256kbyte
5
430
レガシーシステムにどう立ち向かうか 複雑さと理想と現実/vs-legacy
suzukihoge
14
2.2k
Click-free releases & the making of a CLI app
oheyadam
2
120
Compose 1.7のTextFieldはPOBox Plusで日本語変換できない
tomoya0x00
0
190
ECS Service Connectのこれまでのアップデートと今後のRoadmapを見てみる
tkikuc
2
250
ペアーズにおけるAmazon Bedrockを⽤いた障害対応⽀援 ⽣成AIツールの導⼊事例 @ 20241115配信AWSウェビナー登壇
fukubaka0825
6
2k
Laravel や Symfony で手っ取り早く OpenAPI のドキュメントを作成する
azuki
2
120
Snowflake x dbtで作るセキュアでアジャイルなデータ基盤
tsoshiro
2
520
Hotwire or React? ~アフタートーク・本編に含めなかった話~ / Hotwire or React? after talk
harunatsujita
1
120
Contemporary Test Cases
maaretp
0
140
3 Effective Rules for Using Signals in Angular
manfredsteyer
PRO
1
100
Figma Dev Modeで変わる!Flutterの開発体験
watanave
0
140
Featured
See All Featured
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.3k
How to train your dragon (web standard)
notwaldorf
88
5.7k
Keith and Marios Guide to Fast Websites
keithpitt
409
22k
4 Signs Your Business is Dying
shpigford
180
21k
Agile that works and the tools we love
rasmusluckow
327
21k
BBQ
matthewcrist
85
9.3k
Building a Scalable Design System with Sketch
lauravandoore
459
33k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
26
1.4k
5 minutes of I Can Smell Your CMS
philhawksworth
202
19k
Done Done
chrislema
181
16k
Stop Working from a Prison Cell
hatefulcrawdad
267
20k
Measuring & Analyzing Core Web Vitals
bluesmoon
4
130
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. ダークトーン コネクタ
スタンプ
スタンプ