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
210
iOSアプリエンジニアがAWSreInvent行ってきた
totokit4
0
110
re:Inventなんも分からんけどとりあえず全力で行く
totokit4
0
290
カンファレンスを全力で楽しむ技術
totokit4
0
280
デブサミウーマン2023_totokit4
totokit4
5
1.9k
GitHub Copilotを使って ちょっと楽にUnitTestを書けるようになった
totokit4
2
3.4k
Other Decks in Programming
See All in Programming
Day0 初心者向けワークショップ実践!ソフトウェアテストの第一歩
satohiroyuki
0
410
なぜselectはselectではないのか
taiyow
2
310
Django for Data Science (Boston Python Meetup, March 2025)
wsvincent
0
240
Devin , 正しい付き合い方と使い方 / Living and Working with Devin
yukinagae
1
530
私の愛したLaravel 〜レールを超えたその先へ〜
kentaroutakeda
12
3.5k
Develop Faster With FrankenPHP
dunglas
2
2.5k
体得しよう!RSA暗号の原理と解読
laysakura
3
530
신입 안드로이드 개발자의 AI 스타트업 생존기 (+ Native C++ Code를 Android에서 사용해보기)
dygames
0
500
Windows版PHPのビルド手順とPHP 8.4における変更点
matsuo_atsushi
0
370
‘무차별 LGTM~👍’만 외치던 우리가 ‘고봉밥 코드 리뷰’를?
hannah0731
0
530
Compose Navigation実装の見通しを良くする
hiroaki404
0
180
AHC 044 混合整数計画ソルバー解法
kiri8128
0
300
Featured
See All Featured
Code Reviewing Like a Champion
maltzj
522
39k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
[RailsConf 2023] Rails as a piece of cake
palkan
53
5.4k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
30
1.1k
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
102
18k
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
656
60k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
331
21k
Code Review Best Practice
trishagee
67
18k
Automating Front-end Workflow
addyosmani
1369
200k
Build The Right Thing And Hit Your Dates
maggiecrowley
34
2.6k
4 Signs Your Business is Dying
shpigford
183
22k
Making Projects Easy
brettharned
116
6.1k
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. ダークトーン コネクタ
スタンプ
スタンプ