Xcode常用外掛使用及自動生成幫助文件

*一、Xcode 外掛下載:*

VVDocumenter下載: https://github.com/onevcat/VVDocumenter-Xcode

Xcode常用外掛下載：http://pan.baidu.com/s/1sjLnUFj

*二、VVDocumenter安裝方法：*

The best way of installing is by Alcatraz. Install Alcatraz followed by the instruction, restart your Xcode and press ⇧⌘9. You can find VVDocumenter-Xcode in the list and click the icon on left to install.

If you do not like the Alcatraz way, you can also clone the repo. Then build the VVDocumenter-Xcode target in the Xcode project and the plug-in will automatically be installed in ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins. Relaunch Xcode and type in /// above any code you want to write a document to.

If you want to use other text beside of /// to trigger the document insertion, you can find a setting panel by clicking VVDocument in the Window menu of Xcode. You can also find some other useful options there, including setting using spaces instead of tab in the panel or changing the format of generated documentation.

開發中我遇到的問題：下載Xcode常用外掛並解壓至~/Library/Application Support/Developer/Shared/Xcode/Plug-ins，Xcode6.2下其它外掛均可使用，唯獨VVDocumenter不行。百思不得其解。後來安裝了Alcatraz，VVDocumenter才能使用。

*三、appledoc安裝方法：*

1. appledoc下載:https://github.com/tomaz/appledoc
2. appledoc安裝：

The recommended way is to clone GitHub project and compile the tool from Xcode. As cloning GitHub project will create the link to the main repository, it greatly simplifies future upgrading too. To install, type the following in the Terminal:

git clone git://github.com/tomaz/appledoc.git

This creates appledoc directory. Within you can find appledoc.xcodeproj Xcode project; open it and compile appledoc target - this should work out of the box, however your system must meet minimum system requirements, see below. I recommend you copy resulting appledoc executable from build directory to one of the directories in your path (echo $PATH) to make it easily accessible.

Optional: Appledoc is selfcontained and contains the necessary template files. IF you want to modify these default from Templates subdirectory to one of the expected locations:

~/Library/Application Support/appledoc
~/.appledoc

You can also use install-appledoc.sh script to perform quick installation. Open Terminal and switch to appledoc directory. Type following command:

sudo sh install-appledoc.sh (if you need templates add ‘-t default’)
It compiles appledoc and installs its binary to /usr/local/bin and templates (if wanted) to ~/.appledoc by default. You can override this directories with -b and -t options respectively. For example:

sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc

Alternatively with Homebrew:

brew install appledoc

Homebrew does not install templates by default.

*四、appledoc整合Xcode：*

1. Select top of your project in Project Navigator
2. Click Add Target
3. Depending on your project type (iOS or OS X) choose Aggregate Template
4. Create new target. I suggest to call it Documentation
5. Click on Build Phases and add new Build Phase based on Script
6. Paste the script below into the script window
7. Adjust variables in section “Start Constants” as required
8. Uncomment correct ‘target’ for your project and comment out another one depending on your project type.
9. Adjust path to appledoc binary and appledoc’s command-line switches if required
10. When you ready to generate a docset from your project, build Documentation target.
11. Docset will be installed into new loction and will become available to Xcode immediately.
12. To refresh Quick Help (ALT+Click) and (ALT+double-click) you may need to restart Xcode to refresh its index cache.

Below is a working script that can be added to the Xcode Build Phases, Run Script

#appledoc Xcode script  
# Start constants  
company="ACME";  
companyID="com.ACME";
companyURL="http://ACME.com";
target="iphoneos";
#target="macosx";
outputPath="~/help";
# End constants
/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/${company}" \
--output "${outputPath}" \
--publish-docset \
--docset-platform-family "${target}" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold 2 \
"${PROJECT_DIR}"

注：target=”iphoneos”，引號裡內容換成你的工程target名，否則build會有錯。Build成功後，在Xcode開啟 -> help -> Documentation And API Reference,即可檢視生產的工程幫助文件。此方法一。

*五、appledoc使用方法(命令列控制)*

在命令列工具cd到工程所在路徑，然後鍵入

appledoc   --output ./doc --project-name spring3g_v525_test  --project-company "spring3s" --company-id "com.ch" .

或者

appledoc --no-create-docset  --output ./doc --project-name spring3g_v525_test  --project-company "spring3s" --company-id "com.ch" .

這樣在工程目錄下即生成doc資料夾。doc資料夾下有註釋網頁文件。

注：”.“ 和前面的符號一定要加 空格 否則就會報錯。–company-id引數也要傳。新增–no-create-docset引數，會在./doc目錄下生成網頁文件。./doc目錄下docset-installed.txt檔案記錄了生成help Documentation儲存路徑。

*六、appledoc Demo*

Demo下載：https://github.com/JarryChang/AppledocDemo

*七、參考連結：*

1. https://github.com/onevcat/VVDocumenter-Xcode
2. https://github.com/tomaz/appledoc
3. https://github.com/tomaz/appledoc/blob/master/
4. XcodeIntegrationScript.markdown