ストリーミングはほとんどのブラウザと
Developerアプリで視聴できます。
-
XcodeにおけるDocCドキュメントのレベルの向上
優れたドキュメントは、Swiftフレームワークを効果的かつ容易に採用するのに役立ちます。APIに付属させるリッチで概念的な記事を作成する方法を紹介します。文書の構成方法など、記事を書くためのベストプラクティスを確認し、文書をつなぐ管理リンクを自動的に作成する方法を確認しましょう。
リソース
- Adding structure to your documentation pages
- Adding supplemental content to a documentation catalog
- Documenting a Swift Framework or Package
- Formatting your documentation
- SlothCreator: Building DocC Documentation in Xcode
関連ビデオ
WWDC23
WWDC21
-
ダウンロード
♪ (XcodeにおけるDocCドキュメントのレベルの向上) こんにちはBeaです Documentationチームの ヒューマンインターフェースデザイナーです 今回は同僚のJackと一緒に XcodeでDocCドキュメントを 高める方法についてお話します 素晴らしいドキュメントを書き 共有することができるようになりました 今年はSwiftフレームワークのドキュメントを Xcode 13に統合しました このセッションでは私たちが作った フレームワークのドキュメントを 充実させます SlothCreatorです SlothCreatorを使用すると 自然の中にあるスロットのカタログを作成したり 新しいかわいい仮想スロットを 作成することができます このフレームワークの既存の ドキュメンテーションを改善するために Xcode 13で利用可能なドキュメンテーション ページタイプと コンテンツに最適なものを選択する方法 フレームワークのストーリーを 伝えるためにAPIの順序を 整理する方法そしてエクステンションによって ドキュメンテーションの作成方法に 柔軟性を持たせる方法について説明します まずXcodeの新しい機能であるドキュメンテーション ページタイプから始めます Xcode 13には「ドキュメンテーションカタログ」 と呼ばれる新機能がありリファレンス 記事 チュートリアルという ドキュメントウィンドウあるいは Web上に表示可能な3つのページ タイプを作成することができます 各プロジェクトにはそれぞれ 固有のニーズがありますが 通常はさまざまなドキュメントを 用意することをお勧めします リファレンスではライブラリ内の個々の APIに関する簡潔で詳細な情報を提供します これによりテキストの説明コードスニペット および異なるシンボル間の関係を追加できます これがドキュメントのバックボーンです 記事は自由形式のコンテンツを含むページです フレームワークの全体像を示し 特定のタスクを完了する方法を 説明することに長けています それらはしばしば異なるシンボルの 間の点をつないでいます チュートリアルはフレームワークを使用する プロジェクトの段階的なウォークスルーです 実際に実装することで シンボルの組み合わせがどのように連携するかを 理解するのは素晴らしいことです すべての習熟度レベルのフレーム ワーク導入者はチュートリアルの 恩恵を受けることができますが これは非常に初心者に優しい形式 でもあることに注意してください このセッションでは記事に焦点を当てます リファレンスとチュートリアルの情報については 他のWWDCセッションを参照してください SlothCreatorのドキュメントを強化する前に ドキュメントウィンドウの新機能を確認します これですべてのAppleテクノロジーと ご自身のドキュメントがナビゲータに 表示されます ここでSlothCreatorのドキュメントの 現在の状態を確認します SlothCreator SwiftパッケージをXcodeでオープン Productをクリックしてから Documentationをビルドし ドキュメントウィンドウを開きます フレームワークの文書をスクロールしてみると SlothCreatorはすべてのシンボルがここで 参照されていることがわかります 素晴らしいことです しかし このフレームワークを 使ったことのない人の視点から このページを見るとその機能が 一目ではわかりません トップレベルの記事を使って 全体像を描くことができます トップレベルの記事には簡潔なサマリー 画像やコードスニペットなどの内容を含む概要 そして下部には強調したい シンボルがいくつかある トピックセクションがあります 記事を追加するには ドキュメンテーションカタログを 使用してプロジェクトを セットアップする必要があります ドキュメンテーションカタログは Xcodeナビゲーターの中の ファイルですべてのドキュメン テーションファイルが入っています また新しいページタイプを書くことができます これによりドキュメントにすぐに アクセスできるようになり 日常のワークフローでドキュメントの 優先順位を付けやすくなりました その為にSlothCreator ターゲットのソースが含まれている SlothCreator Sources ディレクトリーを右クリックして New Fileを選択します 次にドキュメンテーションカタログが 見つかるまで一覧をスクロールします フレームワークのターゲットに 合わせて名前を付けます SlothCreator ドキュメンテーションカタログを作成すると Xcodeはトップレベルの記事を提供してくれます プロジェクトナビゲータとmarkdownの両方で 「SlothCreator」に変更します それでは記事を始めましょう Markdownを使って記事を書きます まずフレームワークの機能を 1つの文で説明するサマリーを追加します 次にSlothCreatorの主な機能であるリサーチ ケア 視覚化について「Overview」 という タイトルの下にさらに詳細な情報を追加します 最後に開発者が何を見ているか 一目でわかるように画像を追加します 解像度が2倍でダークモードと互換性がある画像か または代替モードがある画像を 追加することをお勧めします ファイルに適切な命名規則を含めることを 忘れないでください まずファイルの名前「sloth」 です 次に画像がダークモードの場合は チルダと「dark」という単語が表示されます 次に「@2x」と入力して尺度係数を指定します 最後にイメージファイルフォーマット この場合は.pngです 画像のサイズと名前が 正しいことを確認したらFinderを開き アセットをドキュメンテーション カタログのリソースフォルダに ドラッグします
次に記事のMarkdownに自分の画像を追加します 最初に感嘆符を追加し 次に画像をアクセス可能にするために 括弧の間に説明を追加し 最後に括弧の間にファイル名を追加しました お気付きかもしれませんが 「@2 x」 または「~dark」 と入力しません Xcodeは自動的に画像を選択するので 入力する必要があるのは画像名だけです さて トップレベルの記事を書き終えました ドキュメントを作成して どのように見えるかを確認します ProductをクリックしてBuild Documentationを 再度選択し ドキュメントウィンドウを表示します 素晴らしいことにSlothCreatorには 明確なサマリーこのフレームワークが 何のためのものかについてのより 多くのコンテキストを提供する概要 およびフレームワークのコア概念を 一目で示す画像があります これで これまでSlothCreatorを 使ったことのない人でもこのフレームワークが 何をするのかの全体像を 素早く理解できるようになります SlothCreatorを使い始めるための 実践的な最初のステップを提供することで このドキュメントをさらに改善することができます それにはタスクに関する記事が役立ちます 事前に記事を準備しておきましたので Finderを開きSlothCreatorの ドキュメンテーションカタログにドラッグします
この記事の目的はこのフレームワークの中核的な 要素であるSlothを作成し そのケアをする方法を人々に教えることです 構造については トップレベルの記事とよく似ています どちらの型にも テキスト 画像 コードスニペットを含められます ここでの最大の違いはコンテンツです これらの違いを確認するために 「Product and Build Documentation」を 選択してドキュメントを再構築します
次にドキュメントウィンドウナビゲータで Getting Started with Slothsを選択します この記事ではSlothの特性と特性を説明することで Slothの作成方法に関する コンテキストをさらに詳しく説明します それはまたslothをどのようにケアし 適切な場所を形成するかについての 実行可能なステップを提供します これによりユーザーはSloth Creatorを早く導入できます 要約すると これまでに作成できるドキュメントの種類と それぞれの用途について説明しました Xcode 13の新機能である 「Documentation Catalog」を紹介しました この機能を使うと すべてのドキュメントファイルを 同じ場所に置くことができ 新しいタイプのドキュメントを 作成することもできます そしてそれを使って より多くのコンテキストを与えたり 特定のタスクに飛び込んだりすることで 自分のドキュメントを強化する 2つの記事を作成しました これらの記事を作成するためにMarkdownと現在 ドキュメント用にサポートしている 新しいファイルを使用しました では このドキュメントをJackに渡しますので Jackはシンボルを整理しドキュメント拡張機能を 作成することによって ドキュメントをさらに 改善する方法について話します ありがとう Beaこれらの記事は素敵です いくつかの新しいページを追加したので フレームワーク全体をガイドする 別の方法があります 以前 BeaはSlothCreatorの 概要を示すフレームワークのページを作成しました ページの下部にはSlothフレームワークの ドキュメントをすべて含んだトピックセクションが DocCコンパイラによって自動的に作成されています 素晴らしいスタートですが改善できると思います それでは一歩下がって伝えたい話について 考えてみましょう SlothCreator APIは主に3つの種類に分類されます slothを研究し創造しています あなたのslothの幸福と健康をケアし その場所であなたのslothを観察します これらのカテゴリーを使ってSlothCreatorの ドキュメンテーションページを 編成することができます フレームワークのトップレベルの ページを次に示します まず 最も重要なページ以外は すべて脇に置いておきます 速度や色など サポートするタイプを 後で別のページの下に整理することができます 次に残りのページをSlothCreatorの 機能を中心にグループ分けします 最後に グループとページを最下位から 最上位に分類します この新しい構成はずっと親しみやすく 特定の機能に興味のあるフレームワークの導入者は どこを見るべきかを知っています 次に これらのテーマを使用するために フレームワークのドキュメントを更新します SlothCreatorプロジェクトと 構築ドキュメントを開いています コンパイラは デフォルトのグループを持つ トピックセクションを各ページに 自動的に追加します でも 追加のmarkdownでカスタマイズできます 以前Beaはフレームワークの記事で ドキュメンテーションカタログを作成しました プロジェクトナビゲータで ドキュメンテーションカタログ内の SlothCreator markdownファイルを 選択します テンプレートには入力するトピックセクションが 既に含まれています 「Essentials」から始めて 第3レベルの見出しでグループタイトルを更新します 次にグループに含めるリンクのリストを追加します 「Getting Started」の記事と Slothタイプから始めます 記事にリンクするには doc URLスキームを使用して 拡張子なしのファイル名を使用します シンボルにリンクするには シンボル名をダブルバックで囲みます 前に作成したカテゴリを使用して 他のすべてのドキュメントページもグループに 編成します 次に再構築して変更を確認します プロダクトメニューで Build Documentationを選択して再構築します ドキュメントが構築されましたが DocCによって診断が生成されています また ここにリンクを間違って入力したようです オートコンプリートで処理しますので 間違いないと思います ここで プロダクトメニューを 使用してドキュメントを再構築し すべての問題が解決したかどうかを確認します
素晴らしい警告はもうありません ドキュメントウィンドウの フレームワークのページでは 「Getting Started」 の新しい記事が 誰もが最初に目にする トピックでありその後にSlothCreatorの メインテーマが複雑な順に続きます 左側のドキュメントナビゲータも各ページの トピックセクションに合わせて更新されるため 探しているページを すばやく見つけることができます 次に ドキュメントの編成方法を確認します すべてのページが自動的に整理され トピックセクションを使用して カスタマイズできます トピックセクションを作成するには 第2レベルのトピック見出しを追加します 次に 第3レベルの見出しを持つグループを追加し その後に現在のページの下に 整理したい他のページへの リンクの一覧を追加します トピックセクションはクラス 構造 列挙 プロトコル などのコンテナシンボルとともに 任意の記事に追加できます フレームワークのドキュメントを 整理するときは 最も重要な機能とテーマおよび開発者がAppを 作成するために一緒に使用する APIを考慮してください サポートページをプライマリ ドキュメントの下に移動して フォーカスと明確さを追加します 基本から始めて 徐々に複雑さを導入していきます フレームワークのページで グループをカスタマイズしたので SlothCreatorのタイプとメンバーを含む すべてのドキュメントを整理します ドキュメント拡張機能を使用すると APIのドキュメントを作成する 方法を柔軟に選択できます カスタムトピックのセクションを ソースコードに追加できますが この追加ドキュメントを 別のファイルに保存しておくと 時間が経つにつれて 確認し保守しやすくなると思います そのためには ドキュメント 拡張機能を使うことができます まず 新しいMarkdownファイルを作成します タイトルのリンク構文を使って APIと関連付けています 次にソースコードの焦点と明確さを 向上させるために サマリーやディスカッションなどの 主要なコンテンツを コードに残し トピックのセクションを抽出します
DocCはビルド時に各ソースコメントと それに対応するドキュメント拡張を 1つのドキュメントページにマージします 拡張機能を使用すると ドキュメントの作成と確認 フレームワークの生成されたインタフェースの改善 ドキュメントの読みやすさの向上を 簡単に行うことができます ここではSlothCreatorの ドキュメントを強化するための ドキュメント拡張機能を追加します 最初に 変更を行う前に slothのページを確認します sloth型のドキュメントコメントと 構築されたドキュメントがあります ソースコードに記述した ドキュメントは素晴らしいものですが Topicsセクションは改善される可能性があり それはドキュメント拡張機能で行うことができます プロジェクトナビゲータで ドキュメンテーションカタログを右クリックして 新しいファイルを追加します テンプレート選択画面で 拡張ファイルテンプレートを選択し 「Sloth」という名前を付けます 次に タイトル内のリンクを 使用して拡張機能ファイルを slothタイプに接続します URLにモジュールの名前を含める必要があります
この前 同僚のBeaがこの構文を 使用してフレームワークの 最上位レベルの記事を作成していたので 見覚えがあるかもしれません 次に カスタマイズしたグループを トピックセクションに追加します 最後に Product> Build Documentationを 使用して再構築し結果を確認します
ソースコードに記述した内容は まだ先頭にあり ドキュメントファイルに作成した トピックのセクションはその後に追加されます ナビゲータでページを展開すると ナビゲータも更新されます Beaと私が行った変更は完了しており 世界と共有する準備ができています Xcodeのドキュメントは見栄えがよく 誰でもSwiftパッケージを ダウンロードして構築できます また ナビゲータの エクスポートボタンを使用して アーカイブをエクスポートし Swiftパッケージをダウンロードまたはビルドせずに Xcodeのドキュメントをブラウズすることもできます 誰でもアクセスできるようにしたい場合は Web上でドキュメントを公開することもできます また この関連セッションで 詳細を確認することもできます Swiftフレームワークのドキュメントを アップグレードする方法を確認しましょう まず フレームワークを紹介し APIがどのように連携するかを 説明する記事を作成します 次に ナビゲーションを改善するために ドキュメントをグループに編成し 最後にドキュメント拡張ファイルの APIリファレンスに詳細を追加します さらに進みたい場合 Webに公開する方法を学習したり 関連する2つのセッションで チュートリアルを使用して 段階的に読者をガイドすることができます Xcode 13はドキュメントの 大きなアップデートであり 何を公開するのかを見ることが できるのはとても楽しみです ご覧いただいてありがとうございます ♪
-
-
4:55 - Top Level SlothCreator Article
# ``SlothCreator`` Catalog sloths you find in nature and create new adorable virtual sloths. ## Overview SlothCreator provides models and utilities for creating, tracking, and caring for sloths. The framework provides structures to model an individual ``Sloth``, and identify them by key characteristics, including their ``Sloth/name`` and special supernatural ``Sloth/power-swift.property``. You can create your own custom sloths using a ``SlothGenerator``, and name them using a ``NameGenerator``. Sloths need careful feeding and maintenance to ensure their health and happiness. You maintain their ``Sloth/energyLevel`` by providing the correct ``Sloth/Food`` and a suitable ``Habitat``. You can exercise your sloth by providing a fun or restful ``Activity``. You can visualize and observe your sloths by adding a ``SlothView`` to a SwiftUI view structure.  -
9:14 - Top Level SlothCreator Article
# ``SlothCreator`` Catalog sloths you find in nature and create new adorable virtual sloths. ## Overview SlothCreator provides models and utilities for creating, tracking, and caring for sloths. The framework provides structures to model an individual ``Sloth``, and identify them by key characteristics, including their ``Sloth/name`` and special supernatural ``Sloth/power-swift.property``. You can create your own custom sloths using a ``SlothGenerator``, and name them using a ``NameGenerator``. Sloths need careful feeding and maintenance to ensure their health and happiness. You maintain their ``Sloth/energyLevel`` by providing the correct ``Sloth/Food`` and a suitable ``Habitat``. You can exercise your sloth by providing a fun or restful ``Activity``. You can visualize and observe your sloths by adding a ``SlothView`` to a SwiftUI view structure. 
-
-
特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。
クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。