WWDC21: Elevate your DocC documentation in Xcode メモ
概要
DocCの3つのタイプのうち、記事(Article)タイプについて解説
Doccの記事(Article)の例
詳細
Xcode13からの Documentation Catalog という機能を使い、3つの Page types を作成できる。
これらは、ドキュメンテーションウィンドウまたはウェブ上に表示可能。
Page types 3種類
- リファレンスドキュメント Reference Document
- 記事 Article
- チュートリアル Tutorial
Documentation Catalog の基本事項
フレームワークについて初見の人でも理解できるように、トップレベルの記事を使って、フレームワークの全体像について説明することができる。
-
トップレベルの記事に含むもの
- 簡潔なサマリー
- 画像やコードスニペットなどの内容を含む概要
- トピックセクション
Top level article
これを生成するためには、Documentation Catalog を設定する必要がある。
記事の種類
Top level article の他に Task article がある。
Task article
Documentation Catalog の作成方法
Xcode のプロジェクトナビゲーターから [Sources] の中の対象のディレクトリを右クリックして、[New File] から [Documentation Catalog] を作成する。
New File から Documentation Catalog を作成
Documentation Catalog の名称は、デフォルト名から適宜変更すると良い。
生成された Documentation Catalog
命名変更された Documentation Catalog
Documentation Catalog への画像の追加
Finder から Documentation Catalog 内の Resources グループへドラッグ&ドロップする。
- ダークモード用画像のファイル名
- ライトモード用画像が flower@2x.png とすると、ダークモード用画像には ~dark をつけ flower~dark@2x.png とする。
- 呼び出すときは flower.png とすれば自動的に適用してくれる。
画像のファイル名
Documentation Catalog の編集
-
記事にリンクする場合
-
<doc:
+ 拡張子なしの記事のファイル名 +>
<doc:GettingStarted>
-
-
シンボルにリンクする場合
- ダブルバックティック
``Sloth``
例
Documentation Extension
ソースコードから構築されたドキュメントでもいいが、Topics の部分は、改善される可能性があり、ドキュメンテーションの拡張機能で書くことができる。
例えば Sloth.swift
に対して Sloth.md
というマークダウンファイルを作成し、タイトルのリンク構文を使って、APIと紐づける。
Sloth.md
に Topics 以降の記述をすると、ドキュメントとして、ソースコードと Sloth.md
に記述した内容がマージされたものが構築される。
# ``SlothCreator/Sloth``
## Topics
### Creating a Sloth
- ``init(name:color:power:)``
- ``SlothGenerator``
オリジナルのドキュメント
拡張されたドキュメント
ドキュメンテーションの拡張機能の追加方法
Xcode のプロジェクトナビゲーターで [Documentation Catalog] を右クリックし、 [New File] から [Extension File] を選択する。
Extension File の追加
なお、[Documentation Catalog] 配下に [Extensions] ディレクトリを作成し、その中に格納すると管理しやすい。
[Extensions] ディレクトリを作成する
参考
WWDC21 のセッション 10167: Elevate your DocC documentation in Xcode
Discussion