WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Host and automate your DocC documentation

Host and automate your DocC documentation

DocCDocumentationXcodeDeveloper Tools
元の動画を見る

ハイライト

Apple が Xcode 13 の DocC にドキュメント アーカイブ ホスティングとサポートを追加xcodebuild docbuildコマンドを使用すると、開発者は Swift フレームワーク、ライブラリ、パッケージのドキュメントを Web サイトに公開したり、スクリプトを使用してオンライン ドキュメントを最新の状態に保つことができます。

主な内容

Swift フレームワークを作成し、API アノテーションが完成しました。問題は依然として残っています。ユーザーは、開発者ドキュメント ウィンドウで完全なドキュメントを読む前に、まずフレームワークを Xcode に取り込む必要があります。

これは新規ユーザーにとってフレンドリーではありません。ユーザーは、フレームワークを採用するかどうかを決定する前に、まずコードをダウンロードし、プロジェクトを開いて、インデックスが作成されるまで待つ必要があります。チーム内でも同じ問題が発生します。ドキュメントが一度エクスポートされると、すぐにメイン ブランチに遅れをとってしまいます。

Xcode 13 の DocC (Documentation Compiler) は、このプロセスをさらに一歩進めています。ドキュメントアーカイブ (.doccarchive) をインポートして Xcode で読み取ることができ、Web ページとしてホストできます。これを既存の Web サイトのディレクトリに配置し、ユーザーが最初にブラウザでドキュメントを読めるようにすることができます。

ホスティング後は、更新の問題を解決する必要があります。アーカイブの手動エクスポートは見落とされがちです。セッションで指定されたメソッドは使用しますxcodebuild docbuildコマンドラインでドキュメントを構築し、スクリプトを使用して生成されたドキュメントを変換します。.doccarchiveWeb サイトのディレクトリにコピーします。スクリプトを CI のマージ後のフックに配置すると、コードとともにオンライン ドキュメントを更新できます。

＃＃詳細

DocC アーカイブのホスティングには 2 種類のルーティングが必要です

（02:38）

DocC ドキュメント アーカイブは、単一ページの Vue.js Web アプリです。サーバーは 2 種類のリクエストを処理する必要があります。

最初のタイプはページリクエストで、パスは次で始まります。/documentation/または/tutorials/始まり。サーバーは、index.html。

2 番目のカテゴリは、静的リソースとデータ リクエストです。ブラウザーは、アーカイブ内の相対パスに基づいて、CSS、JavaScript、データ、画像、ダウンロード、およびメディアをリクエストします。サーバーはこれらのパスをマップする必要があります.doccarchiveディレクトリ内にあります。

（04:49）

# Enable custom routing.
RewriteEngine On

# Route documentation and tutorial pages.
RewriteRule ^(documentation|tutorials)\/.*$ SlothCreator.doccarchive/index.html [L]

# Route files within the documentation archive.
RewriteRule ^(css|js|data|images|downloads|favicon\.ico|favicon\.svg|img|theme-settings\.json|videos)\/.*$ SlothCreator.doccarchive/$0 [L]

キーポイント:

  • RewriteEngine OnApache の書き換えルールを開きます。
  • 第 1 条RewriteRuleと一致するdocumentationまたはtutorialsで始まるURL。 -SlothCreator.doccarchive/index.htmlこれは単一ページのアプリケーションの入口であり、ドキュメント ページとチュートリアル ページのレンダリングを担当します。 -[L]ヒット後、後続のルールの一致を停止することを示します。
  • 第2条RewriteRuleDocC アーカイブのトップレベルのリソース ディレクトリとファイルを明示的に照合します。 -SlothCreator.doccarchive/$0リクエストをアーカイブ内の同じ名前のパスに転送します。
  • 同じサーバーが依然としてプロジェクト Web サイトをホストしており、すべての Web サイト要求をドキュメント アーカイブに転送できないため、ルールは特定のディレクトリをリストします。

xcodebuild docbuildコマンドラインからドキュメントを構築する

（07:28）

Xcode 13が与えるものxcodebuild追加したdocbuildアクション。その使用法は通常のビルドと似ています。スキームを渡し、必要に応じてプロジェクト、ワークスペース、SDK、宛先、または構成を渡します。

ビルド プロセス中に、Swift コンパイラーはソース コード内のパブリック シンボル、シンボル関係、およびドキュメント コメントを収集して、シンボル グラフを生成します。次に、ドキュメント コンパイラは、ドキュメント カタログ内のシンボル マップ、記事、メディア、チュートリアルをマージします。.doccarchive。

（09:17）

# Build documentation for the project.
xcodebuild docbuild                    \
  -scheme "SlothCreator"               \
  -derivedDataPath MyDerivedDataFolder

# Find all the built documentation archives
# to copy them to another location.
find MyDerivedDataFolder               \
  -name "*.doccarchive"

キーポイント:

  • xcodebuild docbuildドキュメントのビルドをトリガーします。 --scheme "SlothCreator"ドキュメントを構築するスキームを指定します。 --derivedDataPath MyDerivedDataFolderスクリプトの検索を容易にするために、ビルド製品を固定ディレクトリに書き込みます。 -find MyDerivedDataFolderビルドディレクトリから検索を開始します。 --name "*.doccarchive"生成されたすべての DocC ドキュメント アーカイブを検索します。
  • セッションでは、依存する Swift フレームワーク、ライブラリ、またはパッケージも同じプロセスを経て、関連ドキュメントが 1 つの場所に配置されると述べました。

スクリプトを使用して Web サイト内のドキュメント アーカイブを更新する

（10:54）

自動公開に必要な手順は 2 つだけです。最初にドキュメントを構築し、次にアーカイブを Web サイトのディレクトリにコピーします。デモの Web サイト ディレクトリは次のとおりです。~/www。

このスクリプトは、チームの自動化プロセスに組み込むのに適しています。セッションでは、これを CI サーバーのマージ後のフックで実行して、ホストされているドキュメントを最新の状態に保つことができると述べました。

（09:18）

#!/bin/sh

# Build the SlothCreator documentation.
xcodebuild docbuild                  \
  -scheme "SlothCreator"             \
  -derivedDataPath MyDerivedDataPath

# Copy the documentation archive to ~/www where we
# host the SlothCreator website and documentation.
find MyDerivedDataPath               \
  -name "*.doccarchive"              \
  -exec cp -R {} ~/www \;

キーポイント:

  • #!/bin/shファイルをシェル スクリプトとして実行します。 -xcodebuild docbuildSlothCreator を構築するためのドキュメント。 --derivedDataPath MyDerivedDataPathスクリプトが Xcode のデフォルトの派生データ パスに依存しないように出力ディレクトリを修正しました。 -find MyDerivedDataPathこのビルド製品を検索します。 --name "*.doccarchive"DocC ドキュメント アーカイブのみに一致します。 --exec cp -R {} ~/www \;各アーカイブを Web サイトのルート ディレクトリに再帰的にコピーします。
  • Web サイトのルートが指定されていますSlothCreator.doccarchive, コピーが完了したらページを更新すると、新しい記事とチュートリアルが表示されます。

Xcode インターフェイスがない場合は、最初にスキームをリストします

（11:18）

スクリプトはスキーム名を知っている必要があります。デモでは、David が Xcode のスキーム セレクターからそれを確認しましたSlothCreator。マシン上で Xcode が開いていない場合は、まずコマンド ラインで使用可能なスキームを一覧表示できます。

xcodebuild -list

キーポイント:

  • xcodebuild -list現在のプロジェクト、ワークスペース、または Swift パッケージで利用可能なスキームをリストします。
  • スキームを見つけたら、その名前を に渡します。xcodebuild docbuild -scheme。
  • セッションは、プロジェクト、ワークスペース、または Swift パッケージを含むディレクトリで呼び出すことをお勧めしますxcodebuild、スキームのみを渡すことができるようにします。

重要なポイント

  • やるべきこと: オープン ソース Swift パッケージのオンライン ドキュメント ポータルを作成します。 価値がある理由: DocC アーカイブは Web サイトで直接ホストできるため、ユーザーは最初に DocC アーカイブを Xcode にインポートする必要がありません。 開始方法: Xcode でエクスポートする.doccarchive、ウェブサイトのディレクトリに置き、プレスセッション.htaccessルール処理/documentation/静的リソースリクエスト。

  • 何をすべきか: 自動的に更新されるドキュメント ステーションを会社の内部フレームワークに追加します。 実行する価値がある理由:xcodebuild docbuildドキュメントはコマンド ラインで生成でき、CI への接続に適しています。 開始方法: 実行するシェル スクリプトを作成しますxcodebuild docbuild -scheme "YourFramework" -derivedDataPath MyDerivedDataPath、次に使用しますfind -name "*.doccarchive"イントラネット サイトにコピーします。

  • 内容: ドキュメントの公開をマージされた固定アクションに変換します。 実行する価値がある理由: セッションでは、ホストされているドキュメントを最新の状態に保つためのマージ後のフックについて明示的に言及しています。 開始方法: CI のマージ後のステップでドキュメント構築スクリプトを実行します。ビルドが成功したら、Web サイトのディレクトリにある古いものを置き換えます。.doccarchive。

  • 何をすべきか: 複数の対象プロジェクトに対して統一されたドキュメント製品リストを生成します。 実行する価値がある理由:find MyDerivedDataPath -name "*.doccarchive"ビルドによって生成されたすべてのドキュメント アーカイブが見つかります。 開始方法: 公開する必要があるスキームごとに実行します。docbuild、すべて集めてください.doccarchiveをクリックし、アーカイブ名でリリース ディレクトリにコピーします。

  • 対処方法: 製品の公式 Web サイトに「ドキュメントを読む」ボタンを追加します。 実行する価値がある理由: DocC の Web アプリは、リファレンス ドキュメント、記事、インタラクティブなチュートリアルをレンダリングできるため、ユーザーがプロジェクトの入り口で使用するのに適しています。 開始方法: ボタンのリンクをポイントします。/documentation/トップレベルのドキュメント ページで、index.html。

関連セッション

コメント

GitHub Issues · utterances