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

[appledoc](https://github.com/tomaz/appledoc#quick-install)のコマンドを入力するのが面倒なので、ちょっと簡単な方法を考えてみました。

やりたかったこと
----------------

- 引数入力なしで実行したい。
- プロジェクトごとに設定したい。
- 自動生成したい。

まずはappledocの簡単な説明
------------------------

<img style="display:block; margin-left:auto; margin-right:auto;" src="http://blog.morizotter.com/wp-content/uploads/2014/04/morizotter_blogdoc.png" alt="Doc" title="doc.png" border="0" width="600" height="346" />

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

1. 所定の書式のコメントをファイルに書いておく
2. appledocコマンドを引数とともに入力する。

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

ひな形作成
---------

[appledoc/AppledocSettings.plist](https://github.com/tomaz/appledoc/blob/master/AppledocSettings.plist)をちょっといじってひな形を作成します。

*AppledocSettings.plist*

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

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

<pre class="brush:bash">
$ appledoc .
</pre>

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

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

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

自動生成
-------

*createdoc*

<pre class="brush:bash">
#!/bin/sh
/usr/local/bin/appledoc .
</pre>

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

<img style="display:block; margin-left:auto; margin-right:auto;" src="http://blog.morizotter.com/wp-content/uploads/2014/04/morizotter_blogsh.png" alt="Sh" title="sh.png" border="0" width="600" height="177" />

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

Appledocについて
----------------

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

- [iOS - appledocでドキュメント生成 - Qiita](http://qiita.com/mtgto/items/c97c59d93fe67d748055)
- [ソースコードからApple標準スタイルのAPIドキュメントを生成するappledocの書き方 ｜ Developers.IO](http://dev.classmethod.jp/smartphone/iphone/ios-appledoc-1/)

参考
----

- [tomaz/appledoc](https://github.com/tomaz/appledoc)
- [appledoc/AppledocSettings.plist at master · tomaz/appledoc](https://github.com/tomaz/appledoc/blob/master/AppledocSettings.plist)
- [ドキュメント自動生成のappledocを試してみたよ - Morizotter Blog](http://blog.morizotter.com/2012/10/07/document-appledoc/)