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

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

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

代码托管

文档书写利器,使用的是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的功能。