Swift-DocCの最新情報

Swift-DocCの最新情報

Swift-DocCの最新情報はすばらしいものとなっています。独自のプロジェクトのドキュメントに書き込んだり共有したりする方法を紹介しますので、是非ご覧ください。さらに、Swift-DocCナビゲーションの改善点をはじめ、AppターゲットやObjective-Cコードのドキュメントをコンパイルする方法についても解説します。また、GitHub Pagesなどのホスティングサービスにコンテンツを直接公開する方法も紹介します。

リソース
関連ビデオ

WWDC23
- Swift-DocCで充実したドキュメントを作成
ダウンロード

♪ 落ち着いた雰囲気のヒップホップ音楽 ♪ ♪ こんにちはFranklinです Swift-DocCチームのエンジニアです同僚のEthanと一緒に Xcode 14のSwift-DocCをご紹介しますよりすぐれたドキュメントの構築に役立つツールが満載されています去年ご紹介したXcode 13のSwift-DocCでは Swiftフレームワークでデベロッパを案内できます Swift-DocCでは個別のAPIの参照ドキュメントからこれらのAPIを一緒に使用することで概念的な記事を書くことさらにユーザーがタスクを完了するためのチュートリアルなどを書くことができます今年のXcode 14では Swift-DocCは新しいワークフローを提供しますフレームワークのドキュメント化に加え Appプロジェクトのサポートも追加されチームと協力しやすくなります Objective-CとC APIをSwift-DocCでドキュメントを構築しプロジェクトのAPIをまとめて説明できるようになりますウェブサイトへのコンテンツの投稿は GitHubページなどの静的ホスト環境の即座に利用できるサポートで劇的に容易になりましたまた新しい強力なナビゲーションサイドバーでデベロッパはこれまで以上に容易にコンテンツを発見できます　また Swift-DocCはオープンソースプロジェクトとなりこれらの新しい機能はオープンソースコミュニティで密接に協力して開発されますこのセッションではSwift-DocCと新しいワークフローをご紹介しますまずはプロジェクトのAPIをソースコードに沿ってドキュメント化する方法を説明します次にコンテンツをシームレスにウェブサイトに掲載する方法そして最後にウェブ上の新しいナビゲーションサイドバーをご紹介しますではドキュメントの構築方法から始めましょうソフトウェアプロジェクトには優れたドキュメントは不可欠ですプロジェクトが進化すると共にデベロッパが貢献する際に確実な基準点があるよう機能性と設計を説明することは重要です XcodeのSwift-DocCはコード開発に使用するのと同じツールを使いすばらしいドキュメントを構築するためのツールを提供します今年すばらしいことにSwift-DocCが Appプロジェクトに拡大されましたでは詳しく見てみましょう私がチームと取り組んでいる Appとドキュメントは「Slothy」と言い SwiftとObjective-Cソースファイルが含まれていますまったく新しいプロジェクトでまだドキュメントを構築していなくても「Product」メニューを開き「Build Documentation」を選択します Xcodeはドキュメントウィンドウを開き Swift-DocCが API用に自動的に生成するスタブが表示されますこれはすばらしい開始点となり寄稿者がプロジェクトを移動するのに役立ちますでは手順を踏んでこのコンテンツを appへの貢献のための完全なガイドを構築しましょう各APIがそれぞれどのような動作をするかを教えることから始めドキュメントカタログで高レベルコンテンツを提供します「SlothView」というビューの説明から始めますこのドキュメントがSwift-DocCで可視化されるよう３本の「/」の後にコメントを入力します次にビューを簡潔に要約しますドキュメントビルドページではこのテキストが目立つようにビュー名の真下に表示されます次に追加のパラグラフを使い詳細を入力しますこのコンテンツはページの概要に表示されます Swift-DocCのリンク構文でAPIの参照をアクティブリンクに変えることですばやくPageに移動して詳細を確認できます DocC はこれらのリンクが構築された時に検証し古くなった場合は警告を発生しますそしてこのビューの使用方法の例を提供したい場合は Markdownコードブロック構文でコードリストを追加しますこれで寄稿者はすぐにこのビューの使い方を知ることができますわずかなステップで私のビュードキュメントはこのプロジェクトの寄稿者により便利になりました次は初期化子を文書化しますここでも要約から始めます初期化子とメソッドでは各パラメータを個別に説明するのがいいでしょうそうするにはパラメータが何かという短い説明でパラメータリスト項目を追加しますコンテンツが別々のパラメータセクションで表示されているのがわかりますか？次はこのプロジェクトで定義されている Objective-C APIを見てみましょう Xcode 14で新しく登場するドキュメントObjective-Cコード向け Swift-DocCの包括的なツールです皆さんが使い慣れているMarkdown構文を使い Xcodeのソースエディタの更新されたサポートでプロジェクトのすべてのAPIを一緒にまとめて説明できるようになりました SwiftとObjective-Cから呼び出せるコードではすてきな言語トグルを使いコードを構築している言語でページを検索できます詳細については以下のリンクからデベロッパドキュメントにアクセスしてくださいではこれを「Slothy」プロジェクトに適用します SLOSoundクラスとその初期化子を説明しますこのクラスはSwiftとObjective-Cコードの両方から使えることにお気づきでしょうか Xcodeが提供する言語トグルでは使用している言語でコンテンツを検索できますではSwiftコードに使用する同じMarkdown構文でクラスと初期化子を説明しますかなり良くなりました要約と概要を加え初期化子にはパラメータセクションを追加個別のAPIの説明は以上ですソースコードにコメントを少し入力することで私のプロジェクトの寄稿者は APIの使い方を理解しやすくなりました次はこのApp向けのトップレベルのページの構築ですこれは寄稿者に最初に表示されるページですですのでAppの内容と寄稿の方法をうまく紹介したいと思いますトップレベルページをカスタマイズするにはドキュメントカタログを追加しますソースフォルダを右クリックし「New File」を選択します次に「Document Catalog」を選択しますドキュメントカタログはソースコードドキュメントを補完し追加のMarkdownファイルとメディアを保有しています Xcodeは Appのトップレベルページを自動的に追加します Appの内容の概要を入力しましょうソースコードのドキュメントのコメントで使用したのと同じ構文を使い要約概要画像などのリッチコンテンツを追加これでより魅力的になりましたこれで寄稿者はすぐにAppの内容を把握できますそれだけです Appのドキュメントがかなり改善されプロジェクトの寄稿者にすばらしい基準点を提供できましたトップレベルページを検索してプロジェクトの概要を確認し各ページにジャンプして各APIの詳細を見れるようになりましたドキュメントの書き方と構築方法を見たところで寄稿者に検索しやすくなるように今度はウェブサイトに公開しましょう Ethan お願いします Franklin　ありがとう私たちは「Slothy」AppをSlothCreatorという一般的に便利なSwiftパッケージを使いモジュラー式に構築してきましたナマケモノ関係のAppを開発する他のデベロッパに役に立つようSlothCreatorを公開することがいいアイデアだと思いますその取り組みの一環としてドキュメントをウェブで共有するために Swift-DocCの真新しい簡素化された公開ワークフローを説明します Xcodeでドキュメントを構築した場合 Swift-DocCはドキュメントを含んだ静的バンドルを生成しますこのバンドルは DocCアーカイブと呼ばれドキュメント用の簡易コンテナですドキュメントウィンドウから直接ダウンロードして同僚に送ることができますアーカイブをダブルクリックするだけでドキュメントを開き検索できますが DocC アーカイブはXcodeでドキュメントを開くだけの簡易コンテナではありませんフル機能を備えたウェブサイトも含まれています新しいXcode 14ではDocCアーカイブはほとんどのウェブサーバに直接対応しますこれによりウェブ上でのドキュメントの公開がこれまで以上に容易になりましたほとんどの場合構築されたDocCアーカイブのコンテンツをウェブサーバのルートにコピーするだけでドキュメントをデプロイできますまたこれはDocCアーカイブが GitHubページを含むほとんどのマネージドホスティングサービスに対応します GitHubページは多くのデベロッパが GitHub.comに統合された自身のドキュメントをホストしている人気の方法です SlothCreatorのソースコントロールに GitHubを使用してきたのでドキュメントの公開もGetHubを利用することが理にかなっています GitHubページをよくご存じなら標準のサーバーとは違いウェブサイトはURLのルートパスではなく特定のベースパスで配信されますこういう種類のホスティングでは対応のDocCアーカイブを生成するためには追加のビルド設定でウェブサイトのベースパスを指定する必要がありますこの仕組みを完全に把握し GetHubページなど特定のホスティングシナリオのみでこの構成が必要なのかを理解するために DocCアーカイブのURLが独自のドメインでホストされた場合どうなるかお見せしましょう「Slothy」Appのサイトがすでにあることにします slothy.example.com SlothCreatorのドキュメントを既存のウェブサイトの一部として公開しようと思います SlothCreator DocCアーカイブのコンテンツをウェブサーバーのルートにただコピーしたとすると SlothCreatorの参照ドキュメントは次に表示されます slothy.example.com/ documentation/slothcreator SlothCreatorパッケージのチュートリアルは「tutorials」パスに配置されますしかしこの場合自己のドメインに公開するのではなく代わりにドキュメントをGitHubリポジトリで保存するために GitHub Pagesが提供するドメインで公開しますリポジトリ向けにGitHub ページサイトを構築するとそのウェブサイトのURLはルートパスではなくリポジトリの名前に一致するベースパスに配置されます一般的にusername.github.io /リポジトリ名となります参照やチュートリアルドキュメントパスはそのベースパスに追加されますこのベースパスはリポジトリに一意なので GitHubページへの公開用にDocCアーカイブを構築する前にSwift-DocCに内容を説明する必要があります Xcode 14ではこのユースケースのためだけに新しいビルド設定が構築されました DocC Archive Hosting Base Pathのベースパス設定がGitHubリポジトリの名前になるように構成したら今後のすべてのドキュメント構築の準備ができましたこれを実践してみましょう SlothCreator Swiftパッケージを開きました Franklinが先ほどSlothy Appの依存関係としてお見せしましたねこのパッケージを広範囲な使用のために公開する間近なのでGitHubページ向けに準備したドキュメントを公開しますフレームワークの「project settings」を開きマウスをXcodeのプロジェクトナビゲータに移動し SlothCreatorアイテムを選択します SlothCreator目標を選択し「Build Settings」タブを開きますこの場合 Swift-DocC関連の設定を探していますなのでDocCで絞り込みます次にDocC Archive Hosting Base Path設定でリポジトリの名前をsloth-creatorにしますすばらしい次はドキュメントの構築ですマウスを「Product」メニューに移動させ「Build documentation」を選択します Xcodeがプロジェクトをコンパイルしドキュメントを生成したらドキュメントウィンドウが開きますこれはドキュメントのトップページですこれをエクスポートしますマウスをドキュメントナビゲータに移動し「SlothCreator」の技術の項目いカーソルを当て「Context」メニュー「Export」をクリックリポジトリのルートにある「docs」というディレクトリにエクスポートしますなぜならドキュメントのウェブサイトを公開するためにこのように GitHubを構成したからです
次は変更を GitHubにプッシュします Xcodeのメインウィンドウに戻り「Source Control」メニューで「Commit(合意)」をクリックします私のドキュメントのコンテンツを保有する Docsディレクトリを選択し合意メッセージを書きますこの変更をプッシュしたら
完了です公開されたサイトを見てみましょう GitHub.comでリポジトリを開きます
READMEでドキュメントサイトのリンクを掲載しているのでそれをクリックしると到着しました SlothCreatorのために取り組んだドキュメントがウェブで簡単にアクセスでき満足していますこれはSlothCreatorを自分のプロジェクトで使用したいと考える方に非常に便利になるでしょう SlothCreatorのドキュメントを一度デプロイしたのでリポジトリのドキュメントが変更するたびにデプロイメントが自動的に行われることを望んでいます SlothCreatorをSwift パッケージとしてリリースするので新しいSwift-DocC Swift Package Managerプラグインがとても役に立つでしょう Swift-DocCプラグインを使用すると Swiftパッケージ用のドキュメントの構築をかなり簡素化することができますプラグインのドキュメントは下にリンクされています是非ご覧ください GitHubページやその他のホスティングサービスでドキュメントのデプロイメントを自動化するのに最適な開始点となりますもちろん Swift-DocCはXcode 13で発表された xcodebuild docbuildコマンドラインインターフェースでXcodeプロジェクト向けのコマンドラインサポートを引き続き提供します xcodebuildを使用してGitHubページへのデプロイメントを自動化する方法は下にリンクされています新しく向上されたウェブ用Swift-DocC向けの検索とナビゲーション体験が今年発表されます新しいナビゲーションサイドバーが SlothCreatorドキュメントの閲覧者にいかに便利かフレームワークの特長を見てみましょう SlothCreatorのGitHubページに戻りページの左側を見ると新しいナビゲーションサイドバーがあります CareScheduleの項目にマウスを移動し三角ボタンをクリックしてメニューを拡大しますするとページを完全に開かなくてもページがCareScheduleの子として整理されているのがわかりますこの場合型の初期化子にそのまま移動することにしますフレームワークを通じて移動し FoodGeneratorやSlothFood項目を拡大し最終的に「枝」ページを開きますページ間を移動する間サイドバーの状態はそのままですでにアクセスしたページを追跡できますフレームワークを自然に探索できるところにとても感謝しますでもこのフレームワークにすでに精通していて特定のシンボルを探している場合は？サイドバーの下にあるフィルターフィールドがこれに最適ですナマケモノのエネルギーレベルを上げるAPIを探しているとしますマウスをナビゲータの下に移動しフィルタバーを選択し「エネルギー」と入力します完璧です energyLevelプロパティのドキュメントが私が探していたものです Xcode 14のSwift-DocCが提供する新しい検索体験は皆さんのドキュメントサイトを次のレベルに引き上げます是非お試しください XcodeのSwift-DocCの統合はすべてのプロジェクトの文書化をサポートするようになりプロジェクトがXcodeでもSwiftパッケージでも Objective-Cと Appとフレームワーク目標のSwiftコードが含まれます Xcode 14によるDocC アーカイブは GitHubページを含む人気のホスティングサービスに即座に対応しますより広範囲のオーディエンスにドキュメントを提供するには革命的なツールです最後にSwift-DocCはウェブで強固な新しいナビゲーション体験を提供しますナビゲーションサイドバーはサイトでのドキュメントの探索と検索に新しい方法を提供します新しいSwift-DocCサイドバーについてや最高のドキュメントを作成して新しい機能を活用する方法については『Swift-DocCコンテンツを見つけやすくする』をご覧くださいドキュメントの詳細については『DocCを使ったインタラクティブなチュートリアルの制作』でAppやフレームワークを通じてデベロッパを案内する方法をご覧ください皆さんがXcode 14で書き公開するドキュメントを見るのが楽しみですご清聴ありがとうございました ♪

/// A view that displays a sloth.
///
/// This is the main view of ``SlothyApp``.
/// Create a sloth view by providing a binding to a sloth.
///
/// ```swift
/// @State private var sloth: Sloth
///
/// var body: some View {
///     SlothView(sloth: $sloth)
/// }
/// ```
struct SlothView: View {
    // ...
}

4:25 - Documenting an initializer

struct SlothView: View {
    /// Creates a view that displays the specified sloth.
    ///
    /// - Parameter sloth: The sloth the user will edit.
    init(sloth: Binding<Sloth>) {
				// ...
    }
}

5:24 - Documenting the SLOSound Objective-C class

/// A sound that can be played.
///
/// Use an instance of this type to play a sound
/// to the user in response to an action or
/// event.
@interface SLOSound : NSObject

/// Creates a sound given its name and path on
/// disk.
///
/// - Parameters:
///   - name: The name of the sound.
///   - filePath: The path to the sound file on disk.
- (id)initWithName:(NSString *)name
          filePath:(NSString *)filePath;

@end

6:48 - Documenting the top-level page for the Slothy app

# ``Slothy``

An app to create and care for custom sloths.

## Overview

Slothy is an iOS app that allows users to create and care for virtual sloths.

![An illustration displaying the UI for finding, creating, and taking care of a sloth in Slothy.](slothy.png)

The Slothy app project contains views to present Slothy's user interface, and utilities to play sounds as the user interacts with the app.

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。

リソース

関連ビデオ

WWDC23