🖥️

WWDC21: Elevate your DocC documentation in Xcode メモ

2023/05/20に公開

概要

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

Doccの記事(Article)の例
Doccの記事(Article)の例

詳細

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

Page types 3種類

  • リファレンスドキュメント Reference Document
  • 記事 Article
  • チュートリアル Tutorial

Documentation Catalog の基本事項

フレームワークについて初見の人でも理解できるように、トップレベルの記事を使って、フレームワークの全体像について説明することができる。

  • トップレベルの記事に含むもの

    • 簡潔なサマリー
    • 画像やコードスニペットなどの内容を含む概要
    • トピックセクション

    Top level article
    Top level article

これを生成するためには、Documentation Catalog を設定する必要がある。

記事の種類

Top level article の他に Task article がある。

Task article
Task article

Documentation Catalog の作成方法

Xcode のプロジェクトナビゲーターから [Sources] の中の対象のディレクトリを右クリックして、[New File] から [Documentation Catalog] を作成する。

New File から Documentation Catalog を作成
New File から Documentation Catalog を作成

Documentation Catalog の名称は、デフォルト名から適宜変更すると良い。

生成された 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 の追加
Extension File の追加

なお、[Documentation Catalog] 配下に [Extensions] ディレクトリを作成し、その中に格納すると管理しやすい。

[Extensions] ディレクトリを作成する
[Extensions] ディレクトリを作成する

参考

WWDC21 のセッション 10167: Elevate your DocC documentation in Xcode

Discussion