mac下如何使用appledoc生成文档

前言

近期手头项目需要出一下文档，方便使用者查阅。调研了目前比较流行的三款文档生成工具HeaderDoc,Doxygen,appledoc。

Doxygen

Doxygen是C++源码生成文档的标准工具，同时也支持很多其它语言如：C,Objective-C,C#,PHP,Java,Python等等。然而，它生成的文档风格和官方文档的风格差了十万八千里，并且配置复杂。

HeaderDoc

HeaderDoc是苹果官方的文档生成工具。Xcode9以前在安装完Xcode后就可以使用，Xcode9是个重构版本，并没有继承这个。该工具对注释生成规则比较特别，只生成以/*! */ 的格式的注释。生成文档是分散的，并没有一个汇总文件。

appledoc

appledoc只专注Objective-C源代码，并且能生成和苹果官方相同风格的文档。同时支持生成html和直接编译成docset安装进Xcode。代码开源在github上，作者会及时跟开发者沟通。

安装

官方推荐做法是克隆GitHub项目并从Xcode编译该工具。由于克隆GitHub项目将创建与主存储库的链接，它也极大地简化了未来的升级。要进行安装，请在终端中输入以下内容：

git clone git://github.com/tomaz/appledoc.git cd ./appledoc sudo sh install-appledoc.sh(如果需要安装模板文件，需添加'-t default') 

还可以使用Homebrew进行安装

brew install appledoc 

注意：Homebrew默认不会安装模板

安装完成，验证一下是否成功,如果显示版本号则证明安装成功。

appledoc --version 

使用

为了演示使用，我创建了测试工程，代码如下

完成了代码的书写，切换到命令行，cd到源码所在的目录，执行以下命令

appledoc -p project_name -v project_version -c company_name --company-id company_id -o ./doc . 

如果不想生成docset，可以添加—no-create-docset。想了解更多的话，命令行下可以通过appledoc —help查看。

生成的html：


很像苹果官方文档的风格吧~

部署

生成好的html如何部署到服务器？我的项目是在github,可以通过github pages来实现。简单说就是在github账号下新建一个username.github.io的仓库，然后将生成的doc目录下html目录中的全部内容上传到github该仓库下，然后就可以通过在浏览器中输入 http://username.github.io 来访问生成的文档了