利用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編寫文檔