DocCドキュメントのホストと自動化

こんにちはDavidです Documentation Toolsチームのエンジニアです このセッションでは次の2つを学びます DocCドキュメントのホスティングと ドキュメント作成の自動化についてです まず Xcodeでのドキュメント作成方法と サーバー上で作られたドキュメントアーカイブを サーバーでホストする方法を説明します 次に ドキュメントの 作成と自動化の方法について 詳しく説明します

講演では 同僚と私が取り組んでいるプロジェクト 「SlothCreator」 を紹介します

始める人々助けるWeb サイトを作りました そして今 Xcode の新しいドキュメント機能で Web サイトで直接ホストできる ドキュメントバージョンを作成できることに 興奮しています これにより 作業はさらに簡単になります では　その方法を見ていきましょう

Xcode 13 の新機能で Swift フレームワークライブラリ パッケージのドキュメントを 簡単に作ることができます セットアップなしですぐに使い始めることができ 徐々に 追加の資料を使って ドキュメントを拡張できます

また 同じくらい簡単に 「開発者向けドキュメント」ウィンドウから ドキュメントをエクスポートできます

エクスポートされたドキュメントアーカイブを 他のユーザーと共有して Xcode にドキュメントをインポートして読んだり オンラインでホストすることができます

Xcode のドキュメントや シンボルのドキュメント作成について 詳しくは 「XcodeにおけるDocCドキュメントについて」 で VictoriaとEthanに話してもらいます このプレゼンの後半ではコマンドラインで ドキュメント作成を自動化する方法について 解説します 今はまだ Xcodeサーバーにエクスポートした ドキュメントアーカイブを使用します

ドキュメントアーカイブは Xcode でドキュメントを読んだり オンラインでホストするための すべてのデータを保持するコンテナです

これは参照ドキュメントと 豊富でインタラクティブなチュートリアルの 両方をレンダリングするため 使用される単一ページのVu.js Web Appとして 構成されています

ドキュメントアーカイブをホストするために サーバー処理に必要な２つの異なる リクエストタイプがあります /documentation/か/tutorials/ で始まる リクエストURL がWeb Appにロードされ 追加のファイルとデータにリクエストがある ドキュメントおよびチュートリアルページの リクエストURL は ドキュメントアーカイブのファイルの１つ 相対ファイルパスと一致します

ページを構成するリクエストの例と サーバーの応答方法を 見てみましょう

ホストドキュメントを開発者が閲覧し ブラウザのリクエストが /documentation/か/ttutorials/ で始まる場合 サーバーはドキュメントアーカイブにある index.html ファイルで応答する必要があります

このファイルはドキュメントアーカイブの CSS と JavaScript を参照しブラウザは Web Appに 残りの部分のロードをリクエストします

読み込まれるとWeb Appは ページのコンテンツ参照する画像やメディアを リクエストします

index.htmlの参照ファイルと Web Appにロードされるコンテンツと メディアの両方がドキュメントアーカイブの フォルダ構造と同じ URL を使います

ホスティングサーバーが受信リクエストに対応する 必要性を見てきたので 次は デモで見てみましょう 多くの方はWebサイトをホストするサーバーを 既に持っているかもしれません 今回はApache サーバーを使ってますが カスタムルーティングは任意のサーバーで可能です

これは 「SlothCreator」 のWebサイトです ページの中央にある最初の説明の下に 「Read Documentation」ボタンを追加しましたが まだ機能しません では それを修正しましょう

ドキュメントアーカイブをWeb サイトの ホストディレクトリにコピーし 空の .htaccess ファイルを追加しました しかし ルーティングを設定していません

追加すべき２つのルーティングルールは ドキュメントチュートリアルページ用と 追加ファイルとデータ用です

初めのルールで 一致させたいパターンは最初のパス構成要素として /documentation/か/ttutorials/で始まる 任意の URLです

このパターンに一致するリクエストがあれば ドキュメントアーカイブ内の index.htmlに再ルーティング したいと思います

最後に リクエストがルールに一致した場合 「ルールの評価を停止」するフラグで ルールを終了します

2 番目のルールでは パターンについてより明確になります このサーバーでWebサイトもホストするため ドキュメントアーカイブのファイルにリクエストを 再ルーティングする必要はありません

ドキュメントアーカイブを見ると パターンに一致するトップレベルのファイルや フォルダがわずかに あることがわかります そこで すべてに一致するパターンを追加します

この場合 リクエストURLは ドキュメントアーカイブの1 つのファイルに対する 相対パスのため 一致した パターンでリクエストを再ルーティングし SlothCreator.DocCarchiveが先頭に付きます 先ほどと同様に 「ルールの評価を停止」のフラグを追加しました

Web ページをリロードし ドキュメントのリンクをクリックすると サーバーが Web サイトとドキュメントの両方を ホストしていることがわかります

「SlothCreator」のメインページでは 重要なシンボルが上位タスクの関連トピックに グループ化されています

そして これら各グループは関連シンボルを より具体的なトピックに分類します

DocC には様々なプロジェクトに適合するよう シンプルなデザインが組み込まれてます これにより「SlothCreator」 のように プロジェクトの見栄えがよく エレガントなドキュメントを簡単に作成できます ドキュメントのコピーを Web サイトでホストしたので ドキュメントアーカイブのビルドとアップデートを 自動化する方法を見ていきましょう そのためにはxcodebuild を呼び出す スクリプトを書きます スクリプトができたら 新しく変更されるたびに スクリプトを実行できるため ホストドキュメントは 常に最新の状態になります Xcode 13 の新機能 xcodebuild の新しいdocbuild アクションを使い コマンドラインにドキュメントを作成できます

Xcode または xcodebuild で ドキュメントをビルドすると それも標準ビルドのように 機能します

ビルド中に Swiftコンパイラはすべてのパブリックシンボル その関係 また ソース内のドキュメントコメントに 関する詳細情報を収集しドキュメントコンパイラに シンボルグラフと呼ばれるファイルとして渡し Xcode でドキュメントを読んだり オンラインでホストしたりするために 必要なすべてのデータを含む ドキュメントアーカイブを 作成します ターゲットにプロジェクトの 追加の記事 メディア等の ドキュメントカタログが関連付けられている場合 ドキュメントコンパイラは ドキュメントアーカイブを作成するときに そのすべてのコンテンツを シンボル情報と組み合わせます

ドキュメントカタログの 詳細については 「XcodeにおけるDocCドキュメントのレベルの向上」 で同僚のビーとジャックが 様々な種類のドキュメントについて語り それらを活用して開発者が プロジェクトを学ぶための 優れた方法について 説明しています

ドキュメント作成の適用はターゲットだけでなく Swift フレームワークライブラリまたパッケージに 依存関係がある場合は すべてに同じプロセスが適用されるため プロジェクトに関連するすべてのドキュメントを 1 か所で入手できます

スクリプトでホストドキュメントの 作成と更新を自動化しようとするのに コマンドラインの xcodebuild は最適です

xcodebuild の新しいdocbuild アクションは デフォルトと同様に機能し ドキュメントも作成します

ビルドアクションのように ビルドスキームとそのスキームが属する プロジェクトまたはワークスペースを渡します

また プロジェクトワークスペース Swift パッケージを含むディレクトリから xcodebuild を呼び出して スキームだけを渡すこともできます プロジェクトとスキームによっては SDK 宛先 構成など 他のフラグを渡しプロジェクトのビルド方法を カスタマイズすることもできます

リクエストは不要ですが より簡単にできるよう ビルド製品とビルドドキュメントが 記述されるカスタムのderivedDataPath を 指定します

ビルドが完了すると .DocCarchive拡張子を使って すべてのビルドドキュメントアーカイブを検索し 各アーカイブを 別の場所や別のマシンにコピーできます

それをデモで見てみましょう

これは 前からのホストドキュメントです 関連シンボルをトピックにグループ化するため 開発者は特定のタスクの コアタイプを簡単に見つけることができます

このバージョンを作成後同僚が Essentials セクションに表示される 新しい記事やチュートリアルを追加しました ですので 今は最新のドキュメントを作成し Web サイト更新の自動化スクリプトを書く 絶好の機会です

これまで見てきたように xcodebuild の docbuild アクションを呼出しビルドドキュメントし ドキュメントアーカイブを検索し Web サイトの ホストディレクトリにコピーして Web サイトを更新します

Xcode のスキームセレクター にも同じ表示がされるため 渡す必要があるスキームはわかっています Xcode を開いていない場合はコマンドラインで xcodebuild-list を実行し 利用可能な全てのスキームを リストにすることもできます

ここでも カスタムのderivedDataPath は必要なく ビルドドキュメントの記述されている場所を 簡単に追跡できます

ビルドが完了したら ドキュメントアーカイブを検索し それらのアーカイブをWeb サイトの ホストディレクトリにコピーできます

これでスクリプトを実行する準備ができました

更新すると 追加された記事とチュートリアルが Essentials セクションに表示されます

最新の変更で ドキュメントはさらに完全なものになります 「SlothCreator」 を初めて使用する方には 記事の内容や チュートリアルの手順などを参照するのに

最適な場所が用意されています

ホストドキュメントの更新は スクリプト実行と同じくらい簡単です 継続的インテグレーションサーバーで post-merge フックの一部を実行すると ホストドキュメントを常に最新の状態に 保つことができます

このセッションで説明した内容を要約すると ドキュメントアーカイブの共有したり オンラインでホストして Xcode 使用前でも フレームワークの利用者に 優れたドキュメント体験を提供できることです また コマンドラインにドキュメントを作成すると 自動化ワークフローに ドキュメントを含めることができます

DocC ドキュメントについて詳しく知りたい場合 「XcodeにおけるDocCドキュメントについて 」で Xcode の新しい ドキュメント機能がわかり易く紹介されています

「Elevate your DocC documentation in Xcode」は DocC カタログを使用して ドキュメントを強化する方法について 「DocCを使ったインタラクティブな チュートリアルの製作」では アイデアを構築しプロジェクトのための チュートリアル作成方法を詳しく説明しています ご覧いただきありがとうございました [音楽]