WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Elevate your DocC documentation in Xcode

Elevate your DocC documentation in Xcode

DocCDocumentationXcodeSwift
元の動画を見る

ハイライト

DocC の Documentation Catalog は記事（Articles）と拡張ファイル（Extensions）に対応し、Topics で API ナビゲーションを整理できます。これにより、フレームワークのドキュメントは自動生成された一覧から、ストーリー性のある構造化コンテンツへ変わります。

主要内容

あなたのフレームワークに 50 個の公開 API があるとします。DocC はデフォルトでアルファベット順に並べるため、ユーザーは長い一覧を見てもどこから始めればよいか分かりません。これらの API を整理し、「まずこれを学び、次にこれを学ぶ」と伝える方法が必要です。

DocC の記事と拡張ファイルの仕組みは、この問題を解決するためのものです。

詳細

Documentation Catalog

（03:59）

Documentation Catalog は、すべてのドキュメントファイルを含む特別なディレクトリです。

SlothCreator.docc/
  SlothCreator.md          # フレームワーク概要記事
  GettingStarted.md        # 入門チュートリアル記事
  Sloth.md                 # 型の拡張ファイル
  Resources/
    sloth.png              # 画像リソース

作成方法：Xcode で Sources ディレクトリを右クリックし、New File → Documentation Catalog を選びます。

（04:55）

キーポイント:

  • .docc 接尾辞のディレクトリ
  • Markdown 記事と拡張ファイルを含む
  • Resources サブディレクトリに画像などのリソースを置く
  • ソースコードと同じ target に配置する

トップレベル記事

（05:00）

トップレベル記事はユーザーが最初に見るページであり、「このフレームワークは何をするものか」に答える必要があります。

# SlothCreator

Create and care for adorable virtual sloths.

## Overview

SlothCreator provides everything you need to research,
create, and care for sloths in your app.

![A cute sloth](sloth)

## Topics

### Essentials

- ``Sloth``
- ``Habitat``

### Creating Sloths

- ``SlothGenerator``
- ``Sloth/name``

（05:00）

キーポイント:

  • 見出しはフレームワーク名
  • 最初の段落は 1 行の要約
  • Overview で追加の文脈を提供する
  • Topics セクションで関連シンボルを整理する
  • 画像は ![alt](filename) 構文を使う

Topics の整理

（09:14）

Topics は第 3 レベル見出しでシンボルを整理します。

## Topics

### Essentials

- ``GettingStarted``
- ``Sloth``

### Research

- ``SlothGenerator``
- ``Sloth/name``

### Care

- ``Habitat``
- ``Habitat/comfortLevel``

（10:00）

キーポイント:

  • ## Topics は第 2 レベル見出しです
  • ### GroupName は第 3 レベル見出しで、グループを定義します
  • シンボルは二重バッククォートでリンクします
  • 記事は拡張子を除いたファイル名でリンクします
  • グループは複雑度が低いものから高いものへ並べます

拡張ファイル

（13:56）

拡張ファイルを使うと、ソースコードを変更せずに型へ Topics の整理を追加できます。

# ``SlothCreator/Sloth``

## Topics

### Creating a Sloth

- ``init(name:color:power:)``
- ``init?(from:)``

### Inspecting a Sloth

- ``name``
- ``color``
- ``power``

### Caring for a Sloth

- ``sleep(in:for:)``
- ``eat(_:quantity:)``

（15:00）

キーポイント:

  • ファイル名は任意ですが、拡張対象のシンボルと同じ名前にすることが推奨されます
  • 見出しは `ModuleName/SymbolName` 形式を使います
  • 内容はソースコード内のドキュメントコメントと結合されます
  • Topics の整理をソースコードから分離するのに適しています

画像リソース

（05:28）

DocC は Dark Mode 画像と 2x 解像度に対応しています。

sloth.png          # デフォルト画像
sloth~dark.png     # Dark Mode 版
[email protected]       # 2x 解像度
[email protected]  # Dark Mode + 2x

Markdown には基本ファイル名だけを書きます。

![A cute sloth](sloth)

（06:02）

キーポイント:

  • 基本ファイル名には修飾子を付けません
  • DocC が適切なバリアントを自動的に選択します
  • 2x 解像度を提供することが推奨されます
  • Dark Mode 画像には ~dark 接尾辞を使います

重要ポイント

  1. フレームワーク用のトップレベル概要記事を作成する。「このフレームワークは何をするものか」に答え、概要図を提供します。入口 API：Documentation Catalog + トップレベル Markdown ファイル。

  2. Topics で API をストーリーとして整理する。機能ごとにグループ化し、基礎から応用へ並べます。入口 API：## Topics + ### GroupName。

  3. 拡張ファイルで Topics の整理を分離する。ソースコードを簡潔に保ち、ドキュメント構造は別ファイルで管理します。入口 API：拡張ファイル + `ModuleName/SymbolName` 見出し。

  4. Dark Mode 対応画像を提供する。Dark Mode 版は ~dark 接尾辞で命名します。入口 API：sloth~dark.png。

  5. 複雑な型にはタスク記事を書く。API を羅列するのではなく、具体的なタスクの完了方法をユーザーに教えます。入口 API：独立した Markdown 記事。

関連セッション

コメント

GitHub Issues · utterances