背景

本文基于实际工作中的场景，其中的仓库和地址等均是公司内部网址，外部无法访问。但原理是相通的，在本地创建API文档或基于远程仓库创建文档时都可参考。

引擎插件文档采用了sphinx工具，将rst格式的源文件(rst文件采用reStructuredText (reST)标记语言编写，类似markdown)生成为html格式，从而在浏览器打开查看。生成的html格式模板主题采用了sphinx_rtd_theme。当前python的官方文档就是用sphinx工具来生成的。

引擎插件库的源文件仓库地址：公司的gogit仓库(基于Gogs搭建的自助Git服务平台)，引擎插件对应的子目录为http://gogit.oa.com/Engine/engine_doc/src/master/sphinx/source/others

修改即针对device.rst进行。

安装、编辑和发布步骤

  1. 安装python，这里以windows系统为例，安装python3.4版本，当然python2.7或最新的python3.6应该也OK的。

  2. 安装sphinx(可参照https://github.com/sphinx-doc/sphinx)，在命令行输入(安装python之后，一般都会自带安装python的包安装管理工具pip，如果输入下面命令提示找不到pip，则需要安装pip工具，可以参照网上教程执行)：

    pip install Sphinx

  3. 安装sphinx的主题sphinx_rtd_theme(Sphinx theme for readthedocs.org)，在命令行输入：

    pip install sphinx_rtd_theme

  4. 安装tomcat，解压到给定目录(比如E:\apache-tomcat-7.0.82)。

  5. 将others.zip解压，然后解压的目录(连同other目录)copy至tomcat安装目录的E:\tomcat_path\webapps\ROOT下(比如E:\apache-tomcat-7.0.82\webapps\ROOT)。如下图所示：

    注：other目录是已经用sphinx-quickstart命令配置好的文档根目录，如果想自己配置，则可以新建一个目录(比如E:\apache-tomcat-7.0.82\webapps\ROOT\docRoot)，然后执行如下操作：

    • 打开命令行，输入下面命令

      cd E:\apache-tomcat-7.0.82\webapps\ROOT\docRoot

    • 然后输入命令

      sphinx-quickstart

      该命令会自动引导你对该目录进行配置，这些配置用于sphinx构建时候使用。配置完成之后会在目录的source子目录(配置的时候选择源文件和构建文件分离的选项)下生成conf.py文件，该文件里面就是用python语言来编写的配置，可以在配置完成之后打开进行修改。建议在引导过程中，大部分选项直接选按enter键选默认配置即可，但对于“autodoc” extension和是否支持make两个选项，请选择yes。选择支持make的话，则会在该目录下生成make.bat和Makefile文件，这样后续在修改了rst源文件之后，只需要在该目录下执行make html命令，即可将最新rst文件实时生成对于的html文件。(查看make.bat文件，可以发现其只是对sphinx-build命令进行了封装，这样构建的时候更加便捷，所以也可以不用make，直接采用sphinx-build命令将rst文件构建生成html文件，当然sphinx其实支持还支持将rst文件转换成pdf等格式，详细情况可以阅读sphinx的使用文档)

  6. 配置tomcat的http服务端口为8080(避免与常用的http 80端口冲突，在%tomcat_install_path%/conf/server.xml中更改)，启动tomcat，即双击运行E:\tomcat_path\bin\startup.bat(比如E:\apache-tomcat-7.0.82\bin\startup.bat)；
  7. 打开浏览器，输入http://localhost:8080/others/build/html/，此时可查看引擎插件的本地打开文档效果，与http://engine.by.com:8000/doc/sphinx/build/html/others/device.html#完全一致，只是运行在本地tomcat服务器。
  8. 用文本编辑器编辑device.rst(可查阅并熟悉reStructuredText (reST)标记语言的语法，在网上搜索了解该标记语言的语法也可)，完成编辑之后，在文档根目录(比如上面示例E:\apache-tomcat-7.0.82\webapps\ROOT\other)下打开命令行，执行make html,构建完成之后，再次用浏览器打开http://localhost:8080/others/build/html/(或按F5刷新，重新加载)，可以查看到刚才编辑修改过的地方。我们编辑了device.rst之后，先在本地加载预览，符合要求，则提交到gogit仓库http://gogit.oa.com/Engine/engine_doc/src/master，引擎插件对应的子目录为http://gogit.oa.com/Engine/engine_doc/src/master/sphinx/source/others。引擎部采用Read the Docs从gogit的文档仓库http://gogit.oa.com/Engine/engine_doc/src/master将里面的rst文档拉取并构建，然后部署到HTTP server上，从而可以打开http://engine.by.com:8000/doc/sphinx/build/html/index.html查看，关于Read the Doc的原理，请参见其官网https://readthedocs.org/