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.2k
ど・ち・ら・にしようかな♪ JazzyとDocC
https://hey.connpass.com/event/249808/
totokit4
July 20, 2022
Tweet
Share
More Decks by totokit4
See All by totokit4
JAWS-UG20250116_iOSアプリエンジニアがAWSreInventに行ってきた(真面目編)
totokit4
0
190
iOSアプリエンジニアがAWSreInvent行ってきた
totokit4
0
100
re:Inventなんも分からんけどとりあえず全力で行く
totokit4
0
290
カンファレンスを全力で楽しむ技術
totokit4
0
280
デブサミウーマン2023_totokit4
totokit4
5
1.9k
GitHub Copilotを使って ちょっと楽にUnitTestを書けるようになった
totokit4
2
3.3k
Other Decks in Programming
See All in Programming
ISUCON14公式反省会LT: 社内ISUCONの話
astj
PRO
0
180
なぜイベント駆動が必要なのか - CQRS/ESで解く複雑系システムの課題 -
j5ik2o
7
2.5k
2024年のWebフロントエンドのふりかえりと2025年
sakito
1
230
“あなた” の開発を支援する AI エージェント Bedrock Engineer / introducing-bedrock-engineer
gawa
11
1.8k
SpringBoot3.4の構造化ログ #kanjava
irof
2
970
法律の脱レガシーに学ぶフロントエンド刷新
oguemon
5
730
sappoRo.R #12 初心者セッション
kosugitti
0
230
Multi Step Form, Decentralized Autonomous Organization
pumpkiinbell
1
660
個人アプリを2年ぶりにアプデしたから褒めて / I just updated my personal app, praise me!
lovee
0
340
テストをしないQAエンジニアは何をしているか?
nealle
0
130
チームリードになって変わったこと
isaka1022
0
190
DevinとCursorから学ぶAIエージェントメモリーの設計とMoatの考え方
itarutomy
1
640
Featured
See All Featured
Facilitating Awesome Meetings
lara
51
6.2k
Building a Scalable Design System with Sketch
lauravandoore
460
33k
What’s in a name? Adding method to the madness
productmarketing
PRO
22
3.3k
Build your cross-platform service in a week with App Engine
jlugia
229
18k
Gamification - CAS2011
davidbonilla
80
5.1k
Why You Should Never Use an ORM
jnunemaker
PRO
55
9.2k
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
8
270
We Have a Design System, Now What?
morganepeng
51
7.4k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3k
The Language of Interfaces
destraynor
156
24k
Agile that works and the tools we love
rasmusluckow
328
21k
Put a Button on it: Removing Barriers to Going Fast.
kastner
60
3.7k
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. ダークトーン コネクタ
スタンプ
スタンプ