利用Sphinx编写文档

Posted 2020-09-23 纵一苇

 

利用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