Titanium Mobile API的chm文件制作思路

在前一篇[url=http://rensanning.iteye.com/blog/1470646]Titanium Mobile API 1.8.2.chm第1版发布[/url]中，发布了作成的CHM版本API帮助文件，很多朋友对如何做成这个文档很感兴趣。这回给大家提供具体的制作过程。
（最近可能没时间来继续更新这个chm版本的帮助文档了，也希望能有人看了这篇文章后，继续为大家提供最新的chm版帮助文档。）

做成chm文件最基本的就是要做好html版的页面，有了html版的页面后，就好办了，用Visual CHM或者PowerCHM等工具compile一下就能做成CHM文件了！

重点是如何做html版的API页面！这里我们一步一步的来看看如何生成出来庞大的html页面。思路有两个：

[size=medium][color=blue][b]思路一：通过Titanium源码中的yml来生成[/b][/color][/size]

1、下载appcelerator-titanium-mobile源码
Appcelerator将源码公布在Github，从[url=https://github.com/appcelerator/titanium_mobile]https://github.com/appcelerator/titanium_mobile[/url]下载真个源码后放置到本地磁盘。

2、安装Python环境
下载完Titanium Mobile源码后解压，你就会发现apidoc这个文件夹，其下有一个docgen.py文件，就是用来生成API的html文件的Python脚本，所以这里我们想要生成html的话，必须要有Python的环境。

从Titanium的兼容矩阵中可以看到，Titanium使用的Python版本是2.7。所以我们需要安装2.7版本，不要低也不要高哦，不然会编译不过去的。
[url=https://wiki.appcelerator.org/display/guides/Titanium+Compatibility+Matrix#TitaniumCompatibilityMatrix-Python]https://wiki.appcelerator.org/display/guides/Titanium+Compatibility+Matrix#TitaniumCompatibilityMatrix-Python[/url]

从[url=http://www.python.org/download/]http://www.python.org/download/[/url]下载python-2.7.2.msi后安装，具体怎么安装这里就不罗嗦了。

3、安装easy_install
由于要解析yml所以需要到Python的pyyaml模块，我们要下载安装，这里介绍使用easy_installl来方便安装。

从[url=http://peak.telecommunity.com/dist/ez_setup.py]http://peak.telecommunity.com/dist/ez_setup.py[/url]下载ez_setup.py后运行，把Python的Scripts文件夹（例如C:\Python27\Scripts）添加到PATH环境变量里。

然后安装pyyaml和Pygments
# easy_install pyyaml
# easy_install Pygments

4、生成API的html版本
执行docgen.py之后，就可以看到开始生成html文件了。
[img]http://dl.iteye.com/upload/attachment/0066/0342/1f9dfb67-ef8f-39c4-a2bf-261ada96f41a.gif[/img]

生成的html文件会放在dist\apidoc下
[img]http://dl.iteye.com/upload/attachment/0066/0344/85de7576-50c7-3774-955a-bae8279540dd.gif[/img]

其中首页是index.html
[img]http://dl.iteye.com/upload/attachment/0066/0346/f98882c8-f202-33f1-97c7-e1d94e806183.gif[/img]

这里我们看到的html文件是没有做过任何美工的，如果你想美化页面（可以随便修改）的话，可以做一个style.css放到apidoc\templates\html\header.html中
[img]http://dl.iteye.com/upload/attachment/0066/0348/b301b1d8-118c-3a57-ae8a-1590c257e053.gif[/img]
[img]http://dl.iteye.com/upload/attachment/0066/0350/114c3ee1-a82c-3780-a097-b48624d6e1cd.gif[/img]

然后重新执行docgen.py，等生成完html之后，将你的style.css放入dist\apidoc中，这样再看看页面
[img]http://dl.iteye.com/upload/attachment/0066/0352/21d6f778-55f3-3c91-8d23-3083c7063208.gif[/img]

[size=medium][color=blue][b]思路二：通过官方提供的api.json来生成[/b][/color][/size]

官方每次在发布最新版本API的时候，都会提供API Reference as JSON。比如1.8.2版本的话，你就可以通过[url=http://developer.appcelerator.com/apidoc/mobile/1.8.2/api.json]http://developer.appcelerator.com/apidoc/mobile/1.8.2/api.json[/url]来获取到api.json。这个JSON串中包含了所有的API信息（包括各个API之间的链接）。

我们有了api.json之后，就可以通过JSON解析工具反序列化成对象，这里我们使用[url=http://jackson.codehaus.org/]Jackson[/url]，因为它的效率足够高。

其中JSON中的对象结构，这里为大家整理出Class图如下：
[img]http://dl.iteye.com/upload/attachment/0066/0449/3a426c1f-3a23-36ba-9531-b149f2060e90.gif[/img]

查看Class图就可以看到，Module、Method、Event、Property都有一个filename的属性，这也就是说他们是基本的模板，所有的API不外乎其中的一种。我们采用freemaker([url=http://freemarker.org/]FreeMarker[/url]是一个高速的模板引擎，估计Java程序员都应该知道)来做模板文件，具体模板文件如何写，这里也不说了，不是太难。。模板文件的编写可以从官方网页中随便抓取对应的一个页面即可。

首先我们用Jackson反向解析JSON串，我们会得到HashMap<String, Module>的一个Map对象。然后遍历这个Map文件，根据Class图中的继承关系生成各个html文件。

***需要特别提及的是index页的生成，其实就是Map的那些Key。

[color=red]特别要提及的还是。目前官方提供的API的JSON串中，有一些错误，并不合法。
[list][*]Method's return type(returns)
[*]Parameter's type(type)
[*]Property's type(type)[/list][/color]

Java版的源码也上传给大家：[url=http://dl.iteye.com/topics/download/32108354-0214-361f-9afd-c3116686d229]TiJson.rar[/url]

生成完html之后就可以做CHM了，不管是使用Visual CHM或者PowerCHM都很方便。具体如何编译成CHM这里就不说了。
[img]http://dl.iteye.com/upload/attachment/0066/0462/f16ccee0-8c00-3506-93e1-96a8ae142c3b.gif[/img]