Xcode 13はコード内のコメントに基づいてドキュメントを自動生成できるようになりました。
独自のドキュメントページをカスタマイズして追加したり、ドキュメントファイルを他のユーザーと共有したり、ドキュメントファイルをウェブサーバーにホストしたりすることができます。
この記事では、Swift Package向けドキュメントの追加について説明します。
この記事に掲載されている画像は developer.apple.com から公開されています。
ドキュメンテーションカタログを作成する
自前のドキュメンテーションのページをカスタマイズして作成するには、ドキュメンテーションカタログを作成する必要があります。自動生成されるドキュメンテーションでいいという場合には、カタログの作成は必要ありません。
まず、Sourcesフォルダーを選択した状態でキーボードで command-N を押して、Xcodeのテンプレートセレクターを開きます。
Documentation Catalog オプションを選択して新規作成してください。
作成済みの .md ファイルと .docc ファイルのファイル名を、プロジェクト名に変更してください。
[プロジェクト名].docc
- [プロジェクト名].md
ドキュメント類の作成について
公開func, struct, class, enumにコメントを追記してください。
関数名を右クリックし、 Show Code Actions オプションを選択します。次に、Add Documentation をクリックします。
公開機能、構造体、クラスには、public というキーワードを忘れずに付与してください。
/**
ユーザーにドキュメントを選択するように求めます。
# Example #
`Your example code`
*/
@available(iOS 13.0, *)
public struct DocumentPicker: UIViewControllerRepresentable
{ ... }
機能の説明が複数行にわたる場合には、1行目がドキュメンテーションの説明に使われ、残りの部分はディスカッションセクションに置かれます。
例えば、機能の説明が次のようであれば
/// Eat the provided specialty sloth food.
///
/// Sloths love to eat while they move very slowly through their rainforest
/// habitats. They are especially happy to consume leaves and twigs, which they
/// digest over long periods of time, mostly while they sleep.
///
/// When they eat food, a sloth's `energyLevel` increases by the food's `energy`.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
以下のように表示されます。
以下のフォーマットを使用して関数パラメータの説明を追加することもできます
/// - Parameter [Name of the parameter]: [Your descriptions for this parameter]
例えば次のコードを使用すると :
/// - Parameter food: The food for the sloth to eat.
/// - Parameter quantity: The quantity of the food for the sloth to eat.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
以下のページが取得されます :
関数にコメントを1行だけ追加したい場合は、バックスラッシュを3本使用します。
コメント内にマークダウンリンクを追加することもできます :
ドキュメントの作成
ドキュメントを生成するには、Product メニューをクリックして Build Documentation を選択します。
Xcodeはドキュメントを生成し、それを新しいウィンドウで開きます。
左側のメニューからプロジェクト名を選択すると、プロジェクトのドキュメントが表示されます。
自動生成されたドキュメント
Xcodeはビルドシステムの情報を利用して、ドキュメントを自動的に生成します。
必要な作業は、上記の項目に記載された手順に従って、publicクラスのstructとfuncに関する説明を追加することだけです。
カスタマイズされたランディングページを作りましょう
デフォルトのランディングページには、Swiftファイルのリストと自動生成された説明文が表示されます。
[プロジェクト名].mdファイルを編集する、をクリックしてプロジェクト名とカスタマイズされた説明文を書き加えましょう。
# ``DocCDemo``
This is a demo for using DocC to provide documentations for your project.
これでドキュメンテーションをビルドする準備ができ、カスタマイズしたランディングページが表示されるようになりました。
追加のドキュメンテーションのページを作成する
追加のドキュメンテーションのページを作成するには、.doccフォルダーを選択し、キーボードショートカットcommand-Nを用いて、EmptyセクションにDocumentation（空のマークダウンファイル）を追加します。
ドキュメントページでは任意のマークダウン形式のテキストを使用できます。
他のドキュメントへのリンクの追加
- <doc:GettingStarted>を使用して作成したページにリンクします。
他のコンポーネントを追加する
画像やリンクなど、マークダウンで使われる他のコンポーネントを追加できます。
ドキュメントを共有する
ドキュメントを .doccarchive ファイルとしてエクスポートするには、Xcodeのウィンドウでドキュメントの名前を右クリックしてから、Exportをクリックします。
.doccarchiveファイルを直接共有する
.doccarchiveファイルを他の人と直接共有することができます。共有相手がファイルをダブルクリックすると、Xcodeでドキュメンテーションが表示されます。
ウェブサーバー上にドキュメンテーションを公開する
AppleのDocCには、専用のhttpリライト規則が存在します。この記事では、Nginxウェブサーバーを使用した場合について解説します。
まず、生成された.doccarchiveファイル内の全てのファイルを/docs/（またはその他自分で選んだディレクトリー）にコピーしてください。
root@ubuntu-linux-20-04-desktop:/docs# ls
css data favicon.ico favicon.svg img index index.html js theme-settings.json
nginxをインストールしてください
sudo apt-get update
sudo apt-get install nginx
次に、/etc/nginx/nginx.conf のファイルを修正してください：
user root;
worker_processes auto;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
server {
listen 80 default_server;
listen [::]:80 default_server;
location ~ ^/(documentation|tutorial)/ {
alias /docs/;
try_files /index.html =404;
}
location = /data/documentation.json {
alias /docs/data/;
try_files /documentation.json =404;
}
location ~ ^/(css|data|downloads|images|img|index|js|videos)/ {
alias /docs/;
try_files $uri =404;
}
location ~ ^/(favicon.ico|favicon.svg|theme-settings.json)$ {
alias /docs/;
try_files $uri =404;
}
location = / {
return 302 /documentation/;
}
location = /documentation {
return 302 /documentation/;
}
location = /tutorial {
return 302 /tutorial/;
}
}
}
これでNginxのサービスを再読み込みしてご自身のウェブサイトを開き、ドキュメンテーションを確認することができます。
systemctl restart nginx
# systemctl reload nginx
この記事が参考になり、DocCをより生産的に活用いただけるようであれば幸いです。
私の公開されているQiita記事をカテゴリー別にご覧いただけます。
今後ともよろしくお願い致します。