如何为组件编写文档

流程

下载文档编写软件，配置对应环境，编写组建文档，build后提交到git上，合并并发布

准备环境

1. 项目采用sphinx工具来编写。 sphinx是python的一个文档编写工具，按照这个文档编写工具前需要下载python，建议2.7版本 下载 python环境安装后配置下path环境。

2. 安装 sphinx 这个文档软件。 下载sphinx 下载后解压到热议目录，最好别有中文。 进入sphinx解压后的目录，里面会有个setup.py， 当前目录打开cmd ， 执行 python setup.py install 。 这个时候就会下载一大堆依赖包。 把当前目录配置到环境path中

3. python和sphinx都安装完了，就可以fork 当前工程，git clone git@github.com:lorrylockie/tpap-docs.git 这个就是用sphinx生成的文档目录， 进入tpap-docs 目录， 打开cmd，执行 make html 就是build当前文档

4. 当前目录/build/html 即为生成后的结构

文档编写

1. sphinx 用的是rst的语法， http://sphinx-doc-zh.readthedocs.org/en/latest/rest.html 可以边写文档的时候边参考下语法

2. 写组件的时候， 其实可以捷径的编写文档，copy 文档中calendar或者kcharts的文档，里面已经有基础结构了，修改里面的内容替换成你自己组件的内容即可

3. 文档主题结构大概是

   • 组件用途，一句话描述
   • 组件来源（适配于官方哪个组件的）
   • 组件的构造函数和实例方法导航
   • 组件的构造函数和实例方法详细说明
   • demo 例子，一定要提供可运行的demo。让第三方使用的时候就直接可以下载一个源码运行起来

4. 编写完后，make html 打包，然后在build/html下面看效果

demo

每个文档内必须配置组件使用对应的demo，方便开发者一目了然的知道如何使用？这是开发者期待的，我们必须提供 demo为了保证其正确性统一性，demo采用了在SDK环境开发，并且部署到线上TAE环境中，这样就解决了各种”不一致“带来的问题，让demo一定是tae环境下可运行的。 tpap-docs / source / raw / tpap / 此为存放demo的目录 启动tae-sdk,将此目录放到tae-sdk的apps目录中，访问demo中的kcharts.php即可看到目前的效果 参考目前的kcharts和calendar目录编写组建的demo(和实际isv的使用方式一样)

ps: 这里实际上是在tae环境下编写demo代码，是为了保证线上demo一定可在sdk中可运行，所以在sdk编写demo之前，一定是组件已经在tpap中pull request并且被merge，由石霸发布，此时sdk中才可真正使用. demo编写完后，tpap-docs / source / raw / tpap /内的文件即可作为tpap-docs文档的源码，在对应的文档中直接引入进来。

所有这些都完成了，ok，那么提交你的代码吧