WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Create rich documentation with Swift-DocC

Create rich documentation with Swift-DocC

Swift-DocCDocumentationXcodeDeveloper Tools
元の動画を見る

ハイライト

Xcode 15 は、Documentation Preview リアルタイム プレビュー エディター、拡張シンボル ドキュメント、グリッド レイアウト、タブ ナビゲーター、ビデオ埋め込み、カスタム テーマ、その他の機能を Swift-DocC にもたらし、開発者が製品 Web サイトのスタイルと一致した豊富なドキュメントを作成できるようにします。

主な内容

拡張シンボルのドキュメント

Swift の拡張機能は強力な言語機能ですが、以前の DocC は外部型を拡張するシンボルのドキュメント ページを生成しませんでした。これは、SwiftUI を与えることを意味しますImage便利なコンストラクターが追加されましたが、ドキュメントには見つかりません。

(06:21) Xcode 15 はこの問題を解決します。拡張シンボルは、プロジェクト内の他のシンボルと並んで、ドキュメントの「拡張モジュール」領域に表示されます。この機能は完全にコミュニティの貢献によって推進されており、Swift-DocC と Swift コンパイラーへの調整された変更が含まれます。

ドキュメント プレビュー エディター

(08:05) これは、Xcode 15 の最も目を引くドキュメント機能です。ソース コード エディターで、[エディター] > [アシスタント] > [ドキュメント プレビュー] からライブ プレビュー パネルを開きます。文字を入力するたびに、プレビューが即座に更新され、ドキュメントの最終的なレンダリングが表示されます。

Swift ソース ファイル、Objective-C ヘッダー ファイル、Markdown ドキュメント ファイルを切り替えてもプレビュー パネルはアクティブなままなので、プロジェクト全体で記述しながらそれらを表示できます。

リッチページレイアウトの手順

(16:18) DocC は、ドキュメントのレイアウトをより柔軟にするために一連の Markdown コマンドを追加しました。

  • @Row + @Column: グリッドレイアウト、写真とテキストを並べて表示 -@TabNavigator + @Tab:タブスイッチャー、垂直方向のスペースを節約 -@Video: ビデオを埋め込んでインタラクティブ性を高めます -@Links: 関連リンクをカードグリッド形式で表示します -@CallToAction: ページに目を引くアクション ボタンを追加します。 -@PageKind(sampleCode): ページをサンプル コード タイプとしてマークします。 -@PageImage / @PageColor: ページアイコンとテーマカラーをカスタマイズします

カスタムテーマ

(25:22)theme-settings.jsonでは、Web ベースのドキュメントの色とフォントをカスタマイズして、ドキュメント Web サイトと製品 Web サイトの間で視覚的な一貫性を維持できます。カスタム テーマは Web ページの展開にのみ影響し、Xcode 内のドキュメントは引き続き Xcode テーマを使用します。

Quick Navigation

(31:02) Xcode 15 で構築されたすべての Swift-DocC Web サイトは、クイック ナビゲーションをサポートしています。 Xcode の Open Quickly 機能と同様に、Shift-Command-O を押して開き、ページ名を入力するとすぐにジャンプします。

詳細

拡張機能のドキュメント コメントを書く

(08:52) SwiftUI の場合Imageドキュメントを追加するための拡張機能:

import SwiftUI

/// An extension that facilitates the display of sloths in user interfaces.
public extension Image {
    /// Create an image from the given sloth.
    ///
    /// Use this initializer to display an image representation of a
    /// given sloth.
    ///
    ///

```swift
    /// let iceSloth = Sloth(name: "Super Sloth", color: .blue, power: .ice)
    ///
    /// var body: some View {
    ///     Image(iceSloth)
    ///         .resizable()
    ///         .aspectRatio(contentMode: .fit)
    ///     Text(iceSloth.name)
    /// }
    ///

```
    ///
    /// ![A screenshot of an ice sloth, with the text Super Sloth underneath.](iceSloth)
    ///
    /// This initializer is useful for displaying static sloth images.
    /// To create an interactive view containing a sloth, use ``SlothView``.
    init(_ sloth: Sloth) {
        self.init("\(sloth.power)-sloth")
    }
}

キーポイント:

  • トリプルスラッシュ///先頭はドキュメントのコメントを示します
  • 最初の行は概要であり、シンボルリストに表示されます。
  • 次の段落はディスカッション セクションを構成します
  • Markdown コード ブロックを使用して使用例を示します -![alt](filename)ドキュメントカタログからの参照画像
  • `SlothView` 他のシンボルへのリンクを作成する
  • DocC は、画像のライト/ダーク モード バージョンを自動的に照合します。

グリッドレイアウト

(16:31)@Rowそして@Column画像とテキストを並べて配置するレイアウトを作成します。

@Row {
    @Column(size: 2) {
        First, you customize your sloth by picking its 
        ``Sloth/power-swift.property``. The power of your sloth influences
        its abilities and how well they cope in their environment. The app
        displays a picker view that showcases the available powers and
        previews your sloth for the selected power.
    }
    
    @Column {
        ![A screenshot of the power picker user interface with four powers displayed – ice, fire, wind, and lightning](slothy-powerPicker)
    }
}

@Row {
    @Column {
        ![A screenshot of the sloth status user interface that indicates the the amount of sleep, fun, and exercise a given sloth is in need of.](slothy-status)
    }
    
    @Column(size: 2) {
        Once you've customized your sloth, it's ready to ready to thrive.
        You'll find that sloths will happily munch on a leaf, but may not be as 
        receptive to working out. Use the activity picker to send some
        encouragement.
    }
}

キーポイント:

  • @Row複数の行を含む行を定義します。@Column
  • @Column(size: 2)列が 2 つの幅を占めるようにします (デフォルトは 1)。
  • グリッドの合計幅は 4 列であるため、size: 2半分
  • 画像とテキストの順序は柔軟に調整できます（テキストを左、画像を右、または画像を左、テキストを右）

タブナビゲータ

(18:16)@TabNavigator多言語のスクリーンショットを折りたたむ:

@TabNavigator {
    @Tab("English") {
        ![Two screenshots showing the Slothy app rendering with English language content.](slothy-localization_eng)
    }
    
    @Tab("Chinese") {
        ![Two screenshots showing the Slothy app rendering with Chinese language content.](slothy-localization_zh)
    }
    
    @Tab("Spanish") {
        ![Two screenshots showing the Slothy app rendering with Spanish language content.](slothy-localization_es)
    }
}

キーポイント:

  • @TabNavigatorすべてのタブを折り返す
  • それぞれの @Tab("タイトル") がタブページを定義する
  • 同じコンテンツのさまざまなバリエーション (言語、テーマ、プラットフォーム) を表示するのに適しています
  • 垂直方向のスペースを大幅に節約し、長いページスクロールを回避します

ビデオを埋め込む

（19:07）

@Video(poster: "slothy-hero-poster", source: "slothy-hero", alt: "An animated video showing two screens in the Slothy app.")

キーポイント:

  • poster再生前に表示されるビデオのカバー画像です -sourceビデオファイルです -altアクセシビリティの説明を入力します
  • ビデオ ファイルはドキュメント カタログに配置されます

ページのメタデータ

(19:50)@Metadataページレベルの設定を追加します。

@Metadata {
    @CallToAction(purpose: link, url: "https://example.com/slothy-repository")
    @PageKind(sampleCode)
    @PageImage(purpose: card, source: "slothy-card", alt: "Two screenshots showing the Slothy app.")
    @PageImage(purpose: icon, source: "slothCreator-icon", alt: "A technology icon representing the SlothCreator framework.")
    @PageColor(green)
}

キーポイント:

  • @CallToActionページの上部にアクション ボタンを追加します。purpose: linkリンクを表し、purpose: downloadダウンロードを意味します -@PageKind(sampleCode)ページをサンプルコードとしてマークし、特別なタイトルとアイコンを表示します -@PageImage(purpose: card)カード表示時の画像を設定する -@PageImage(purpose: icon)ナビゲーションバーとページ紹介エリアのアイコンを設定する -@PageColorページのテーマの色を設定します (緑、黄、紫、オレンジなどの標準色をサポート)

注目のコンテンツのリンク

(21:55)@Linksページ上部の注目コンテンツ:

@Links(visualStyle: detailedGrid) {
    - <doc:GettingStarted>
    - <doc:SlothySample>
}

キーポイント:

  • visualStyleサポートlist(単純なリスト) とdetailedGrid(詳細なカードグリッド)
  • ドキュメント ディレクトリ内の他のページへのリンク ・リンク先ページが設定されている場合@PageImage(purpose: card)を押すとカード画像が表示されます

カスタムテーマ

(27:04) ドキュメントカタログで作成theme-settings.json：

{
    "theme": {
        "color": {
            "standard-green": "#83ac38"
        },
        "typography": {
            "html-font": "serif"
        }
    }
}

キーポイント:

  • ファイル名は次のようにする必要があります。theme-settings.json
  • colorエリアカバレッジの標準カラー変数 -typographyゾーンコントロールのフォント設定
  • Web ページのデプロイメントのみに影響し、Xcode 内のドキュメントは影響を受けません。
  • その他のカスタマイズ オプションについては、Swift-DocC 公式ドキュメントを参照してください。

重要なポイント

  1. オープンソース フレームワーク用の製品レベルのドキュメント Web サイトを作成します

    • やるべきこと: Swift-DocC を使用して、公式 Web サイトのスタイルと一致する Swift パッケージのドキュメント サイトを作成します。
    • 実行する価値がある理由: ドキュメント プレビューを使用すると、作成プロセスが効率的かつ楽しいものになり、カスタム テーマを使用するとドキュメントをブランド ビジョンに統合でき、GitHub Pages への公開コストはゼロになります。
    • 開始方法: ドキュメント カタログをパッケージに追加し、Markdown 記事を作成し、使用しますxcodebuild docbuild構築と展開

  2. チームの内部フレームワーク用の閲覧可能な API リファレンスを作成します

    • 内容: チームメンバーが API の使用法や内部フレームワークの例をすぐに見つけられるようにします。
    • 実行する価値がある理由: DocC はドキュメントのコメントから API リファレンスを自動的に生成し、クイック ナビゲーションは高速ジャンプをサポートするため、ソース コードを翻訳するよりもはるかに効率的です。
    • 開始方法: パブリック API のドキュメント コメントをトリプルスラッシュで記述します。@Rowそして@Column概念的なコンテンツを整理し、構築後にイントラネットに展開します

  3. インタラクティブなチュートリアルを含む入門ガイドを作成する

    • やるべきこと: 新規ユーザー向けに、導入、コード、および各ステップで期待される結果を含む、段階的な「ゼロから 1」のチュートリアルを作成します。
    • 実行する価値がある理由: DocC のチュートリアル形式は、当然ながらガイド付き学習に適しており、静的な README よりも理解しやすいです。
    • 開始方法: ドキュメント カタログで作成する.tutorialファイル、使用@Tutorial命令はステップを定義し、各ステップで使用するもの@Stepsそして@Codeコードの進化を表示

  4. 複雑な API については、グラフィックとテキストを並べて詳細な手順を作成します

    • 対処方法: グリッド レイアウトを使用して、ドキュメント内にテキストの説明とインターフェイスのスクリーンショットを同時に表示します。
    • 実行する価値がある理由:@Row + @Column縦組み写植よりも絵と文字の関係が明確で読みやすくなります。
    • 開始方法: Markdown ドキュメントで使用する@Rowパック@Column、調整sizeパラメータは列幅の比率を制御します

関連セッション

コメント

GitHub Issues · utterances