uncategorized

appledoc与xcode的集成

今天通过xcode的插件管理工具Alcatraz, 安装了一个文档插件, VVDocumenter-Xcode
有了这个文档插件我就可以很方面的给函数, 文件, 类等添加一些文档信息了, 具体的使用
去看VVDOCUMENTER-XCODE的官方说明.

有了这个文档插件, 我就想着在Xcode的右边栏的Show Quick Help Inspector看到我们加
的一些文档信息, 在网上找了一下, 发现appledoc可以满足我的需求. appledoc
的安装安装方式可以参考官方网站. 因为我用的Mac, 我就使用了Mac上面的软件管理工
homebrew来安装的. 其他的安装方式参考官网.

1
brew install appledoc

关于appledoc的使用帮助, 你可以参考这里用appledoc 生成文档, 因为我们需
要在Xcode直接使用, 网上找了点资料, 需要在借助AppleScript脚本在Xcode里面设置一下
才可以使用的.

首先你要再的家目录下面新建一个.appledoc的文件夹.

1
mkdir ~/.appledoc

然后到这个目录下面新建两个文件:
第一个文件名称appledoc.generate.scpt, 内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#!/usr/bin/osascript

tell application "Xcode"
tell first project

-- variables to export
set projectName to (get name)
set projectDir to (get project directory)
set company to (get organization name)

-- invoke script passing extracted variables
do shell script ("sh ~/.appledoc/appledoc.generate.sh " & projectName & " " & projectDir & " " & company)

end tell
end tell

第二个文件名称appledoc.generate.sh, 内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
#! /bin/sh

# Input arguments:
# $1 -> project name
# $2 -> project path
# $3 -> company name

# dynamic variables
docsURL="http://www.$3.com/docs";
projectsPath="$2/../";
docsPath="${projectsPath}/AppleDocOutput";

#say "project is: $1";
#say "path is: $2";
#say "company is: $3";
#say "project path is: ${projectsPath}";

# create AppleDocOutput folder if not exists
if [ ! -d $docsPath ];
then
#say "create output folder";
mkdir "${docsPath}";
fi

#say "run appledoc";

#invoke appledoc passing computed arguments
/usr/local/bin/appledoc \
--project-name "$1" \
--output "${docsPath}/$1/" \
--docset-feed-url "${docsURL}/%DOCSETATOMFILENAME" \
--docset-package-url "${docsURL}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${docsURL}/$1Doc/" \
--ignore "$1Tests" \
"$2" > "${docsPath}/AppleDoc.log"

好了, 当你在把文件建好了之后, 就要到Xcode里面去设置一下了, 点击菜单栏Xcode->
Behaviors->Edit Behaviors..., 如下图所示:

点击旁边的+号, 起一个AppleDoc的名字, 然后把Run这个按钮选中, 然后选择那个
appledoc.generate.scpt这个脚本文件, 记得给这个脚本添加执行的权限.

你可以给AppleDoc这个Behaviors添加一个快捷键Shift-Cmd-D.

参考:

  1. Generate beautiful code documentation with a simple shortcut using AppleDoc, Xcode custom behaviors and AppleScript!
  2. 用 appledoc 生成文档