文档整体解决方案(readthedocs、github 、sphinx)
这里是总结了一下,用的工具或者平台:readthedocs、github 、sphinx。 使用这三个工具即可轻松创建高效的文档管理库,可以用来翻译,水平再高一点可以写书。
文档托管的平台,能够和常用的GIT阵营的github,HG阵营的Bitbucket,关于这两个平台的讨论比较文章可以参考。
代码托管
文档书写利器,使用的是reStructuredText格式,reStructuredText简明教程。
下面说说书写方法及托管流程
在这里注册一个帐号—>登录。
git的帐号及使用大家应该很熟悉了,在这里不再赘述。创建一个repo以存放sphinx(我测试用的a-test-sphinx-doc)。
安装sphinx,快速入门
jwch的成员有人整理这个文档使用shpinx记笔记,按照这个来就可以。
- 将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
把github中的文档的代码仓库导入到readthedocs
首先在github->repo->Admin-ServiceHooks->ReadTheDocs,激活这个选项。
readthedocs->Import 按照上边的有关字段的提示填写清楚,必要的Name Author Version Repo……,这里注意
conf.py
路径要填写正确(source/conf.py),提交。
这样就文档导入到了readthedocs中,则还是我的测试文档,readthedocs的文档主题简洁,比较不错。当然如果你自己有web服务器,就不用那么麻烦,这里最大好处不用自己维护服务器,可以充分利用github的功能。