🖥️

WWDC21: Elevate your DocC documentation in Xcode メモ

2023/05/20に公開

wwdc

DocC

tech

概要

DocCの3つのタイプのうち、記事（Article）タイプについて解説

Doccの記事（Article）の例

詳細

Xcode13からの Documentation Catalog という機能を使い、3つの Page types を作成できる。
これらは、ドキュメンテーションウィンドウまたはウェブ上に表示可能。

Page types ３種類

リファレンスドキュメント 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 に記述した内容がマージされたものが構築される。

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