首页 > 代码库 > 利用Sphinx编写文档

利用Sphinx编写文档

 

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

 

利用Sphinx编写文档