利用Sphinx编写文档
1、Sphinx简介和使用理由
=================
Sphinx是一个用Python语言编写而成的文档编写工具。用Sphinx编写文档的时候，用户只需要编写符合Sphinx格式要求的纯文本源文件，然后通过Sphinx的命令就可以把纯文本源文件编译成html、pdf等常用格式的文档，这样就实现了通过文本文件自动生成html、pdf等格式文档的功能。
编写文档直接用Word不就是挺好的吗？为什么又要用Sphinx来写纯文本格式的文档呢？
这是因为Sphinx中的文本格式文档可以用版本控制系统跟踪它的变更，同时呢，它又可以非常轻松地生成多种的目标文档格式，比如编写一份Sphinx文档，然后通过工具就用这一份文档生成html、pdf、epub等其他格式的文档了，编写一种文本格式的文档，可以得到很多种其他格式的文档。
然而，word想要转成html就没有那么容易了，而且word文件是二进制文件，所以无法用版本控制系统来跟踪变更。
2、Sphinx在Windows下的安装
===================
Sphinx是用Python语言写成的软件，所以在安装Sphinx之前首要先要安装Python。
Python安装好之后，可以通过Python自带的Pip工具来安装Sphinx。只需要下面这一条命令，就可以完成Sphinx的安装：
pip install Sphinx
3、利用Sphinx制作文档的一般步骤
=====================
一般情况下，用Sphinx来写文档的时候，首先要创建一个Sphinx工程，就像要编写C语言程序在IDE中要建一个工程是一样的道理。建好工程，之后就可以往这个工程中写自己的文档源文件了。源文件编写完成后，就可以生成目标格式的文档了，如果想要html格式就用相应的命令，想要pdf格式也可以用对应的命令来生成。
所以，通常就这么三步：
（1）建文档项目
（2）写文档源文件
（3）编译生成目标格式的文档
4、Sphinx基础知识
============
这里简单介绍一些Sphinx的文档的基本编写知识。详细的情况可以参考《参考资料1》和中文版的《Sphinx使用手册》。
5、发布文档
========
发布文档是什么意思呢？因为Sphinx写文档可以编译成html格式，那么html格式的文档，就可以发布在网上，大家像看网站那样看文档。有一个叫readthedocs.org的网站就可以托管Sphinx生成的文档。
详情可以参考《参考资料4》
参考资料
1、https://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/
2、http://www.jianshu.com/p/56515db85690
3、http://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
4、http://avnpc.com/pages/writing-best-documentation-by-sphinx-github-readthedocs
5、http://www.jianshu.com/p/78e9e1b8553a
来源：https://www.cnblogs.com/zhangzl419/p/7012791.html