Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

totokit4

July 20, 2022
Tweet

More Decks by totokit4

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  15. まずは、Jazzy触ってみた
    2

    View Slide

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

    View Slide

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

    View Slide

  18. できたもの

    View Slide

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

    View Slide

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

    View Slide

  21. 次に、DocC触ってみた
    3

    View Slide

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

    View Slide

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

    View Slide

  24. できたもの

    View Slide

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

    View Slide

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

    View Slide

  27. STORES 決済 での運用方法
    4

    View Slide

  28.   
    ©hey, Inc
    Jazzy DocC
    Objective-Cのドキュメント化 ○ ×
    privateな関数等のドキュメント化 ○ ×
    ドキュメント化するファイルを指定 ○ ×
    チュートリアル等の作成 × ○
    多言語対応 × ×

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  35. おしまい

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  39. ダイアグラムスタイル
    テキスト テキスト
    テキス
    ト テキス

    テキスト
    テキス

    テキスト テキスト テキスト
    テキスト テキスト
    テキス
    ト テキス

    テキスト
    テキス

    テキスト テキスト テキスト
    テキスト テキスト
    テキス
    ト テキス

    テキスト
    テキス

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

    View Slide

  40. スタンプ

    View Slide

  41. スタンプ

    View Slide