文档整体解决方案(readthedocs、github 、sphinx)

这里是总结了一下，用的工具或者平台：readthedocs、github 、sphinx。 使用这三个工具即可轻松创建高效的文档管理库，可以用来翻译，水平再高一点可以写书。

• readthedocs

文档托管的平台，能够和常用的GIT阵营的github，HG阵营的Bitbucket，关于这两个平台的讨论比较文章可以参考。

• github

代码托管

• sphinx

文档书写利器，使用的是reStructuredText格式，reStructuredText简明教程。

下面说说书写方法及托管流程

1. 在这里注册一个帐号—>登录。

2. git的帐号及使用大家应该很熟悉了，在这里不再赘述。创建一个repo以存放sphinx（我测试用的a-test-sphinx-doc）。

3. 安装sphinx，快速入门

jwch的成员有人整理这个文档使用shpinx记笔记，按照这个来就可以。

1. 将sphinx生成的文档和配置 push 到git代码仓库[a-test-sphinx-doc]

evenvi@evenvi-MS-7302:~/mydoc$ git init  
evenvi@evenvi-MS-7302:~/mydoc$ git add .  
evenvi@evenvi-MS-7302:~/mydoc$ git commit -m "test sphinx doc"  
evenvi@evenvi-MS-7302:~/mydoc$ git remote add origin https://github.com/yinlianwei/a-test-sphinx-doc.git  
evenvi@evenvi-MS-7302:~/mydoc$ git push origin master

经过这些就把你的sphinx生成的文档及一些配置文件等，push到了github

1. 把github中的文档的代码仓库导入到readthedocs

2. 首先在github->repo->Admin-ServiceHooks->ReadTheDocs,激活这个选项。

3. readthedocs->Import 按照上边的有关字段的提示填写清楚，必要的Name Author Version Repo……,这里注意 conf.py 路径要填写正确（source/conf.py），提交。

这样就文档导入到了readthedocs中，则还是我的测试文档，readthedocs的文档主题简洁，比较不错。当然如果你自己有web服务器，就不用那么麻烦，这里最大好处不用自己维护服务器，可以充分利用github的功能。