Edited at

Apple風ドキュメント自動生成ツール「appledoc」をもっと簡単に使うTips

More than 5 years have passed since last update.

appledocのコマンドを入力するのが面倒なので、ちょっと簡単な方法を考えてみました。


やりたかったこと


  • 引数入力なしで実行したい。

  • プロジェクトごとに設定したい。

  • 自動生成したい。


まずはappledocの簡単な説明

Appleのドキュメントのようなこのページを簡単に出力できるツールがappledocです。普通にXcodeを利用して作成したプロジェクトがあれば、コメントを少し意識するだけで簡単にそれっぽいドキュメントが生成できます。使い方は、


  1. 所定の書式のコメントをファイルに書いておく

  2. appledocコマンドを引数とともに入力する。

というだけ。簡単といえば簡単です。ただし、ドキュメントに出力するときに引数で設定できる項目が多く、面倒に感じます。もちろん引数を間違えると出力できません。そこで、自分がよく使う設定をplistで書きだしておいて、プロジェクトごとに自分の好きなように手を加えながら利用する方法を考えてみました。


ひな形作成

appledoc/AppledocSettings.plistをちょっといじってひな形を作成します。

AppledocSettings.plist


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>--company-id</key>
<string>your-company-id</string>
<key>--ignore</key>
<array>
<string>ThirdParty</string>
<string>Libraries</string>
<string>Frameworks</string>
<string>Testing</string>
</array>
<key>--logformat</key>
<integer>1</integer>
<key>--print-settings</key>
<true/>
<key>--project-company</key>
<string>your-company</string>
<key>--project-name</key>
<string>your-project-name</string>
<key>--repeat-first-par</key>
<false/>
<key>--verbose</key>
<string>3</string>
<key>--output</key>
<string>./docs/</string>
<key>--create-html</key>
<true/>
<key>--create-docset</key>
<false/>
</dict>
</plist>

出力をHTML形式にして、出力先をコマンドを実行したディレクトリの docs/に指定しています。これをプロジェクトのルートに置いておくと、


$ appledoc .

docs/ 下にhtmlが出力されます。もちろん、docsディレクトリが存在しない場合は作成してくれます。


.
├── AppledocSettings.plist
├── YourProject
├── YourProject.xcodeproj
├── YourProjectTests
└── docs
└── html
├── Classes
├── css
├── hierarchy.html
├── img
└── index.html

こんな感じになるので、管理も簡単です。その他docsetsが欲しかったりした場合は適宜plistの中身を変更して実行します。


自動生成

createdoc


#!/bin/sh
/usr/local/bin/appledoc .

こんな感じのシェルスクリプトを作っておき、Xcodeから実行する。 Project > Build Phases > Run Script

Sh

AppledocSettings.plistのひな形とcreatedocをどこか(Githubだったり、bitbucketだったり。僕の場合は、 ~/tools/Xcode/ )に置いておき、プロジェクト作成したらこれをコピーして使えばいいと思う。


Appledocについて

この辺りに目を通すと良いと思います。


参考