Sphinx編譯docs文檔

標籤：

在使用Python、Django的過程中，經常看到docs目錄，裡面存放著一些txt文字檔，也就是內建的一些協助文檔，裡面有make.bat，在dos目錄下直接執行make，給出的協助是可以轉換成Html、PDF等檔案形式，那麼，怎麼轉換這些協助文檔呢？直接執行make html發現提示sphinx-build不是內部或外部命令，在網上下載了Sphinx，並安裝，再次執行make html時發現還是提示不是內部或外部命令，最後發現，Sphinx安裝後，並沒有在Python安裝目錄中產生Sphinx的模組，而是直接在Sphinx的來源目錄下產生了一個build目錄，直接在目前的目錄中安裝了。

通過尋找協助，直接早dos環境進入sphinx源檔案目錄，在此目錄下執行如下命令：

python sphinx-build.py -b html 需要轉化文檔的全路徑  轉換後文檔的全路徑

例如：我的Sphinx源檔案路徑在C:\Sphinx-1.3.1，Django的docs路徑在C:\Django-1.8\docs，現在將docs內容轉換成html格式，並在docs中建立build目錄，轉換後的html存放目錄，執行命令：

C:\Sphinx-1.3.1>python sphinx-build.py -b html C:\Django-1.8\docs C:\Django-1.8\docs\build，執行後，在build目錄產生了django的協助文檔（Html格式的）。

下列是需要安裝的第三方工具：

1.下載並安裝Docutils：http://docutils.sf.net/。

2.下載並安裝sphinx ：http://pypi.python.org/pypi/Sphinx/1.1。

Sphinx 是用來產生文檔的，可以產生html、htmlhelp/chm、qthelp、devhelp、latex、man 等格式的文檔。

3.在Widnows環境下，開啟命令提示字元，使用cd /d 命令將目前的目錄切換至Sphinx目錄，運行命令：python sphinx-build.py -b html sourcedir builddir，其中，-b後面的字串用於控制輸出文檔的格式，預設為html。sourcedir表示文檔來源檔案夾（一般就是包含conf.py檔案的那個檔案夾），builddir表示產生文檔的目標檔案夾。(註：在Windows環境下，請不要將sphinx檔案夾、sourcedir 和builddir 設定成包含中文的路徑，否則容易出現一些默名其妙的錯誤，例如編碼錯誤。)

Sphinx編譯docs文檔