Python sphinx-build在Windows系統中產生Html文檔

標籤：行修改   ima   line   資訊   lin   9.png   logs   文章   res   

看到前同事發布的“Markdown/reST 文檔發布流水線”基於TFS、Docker、Azure等工具和平台進行文檔發布的介紹說明，不得不在心中暗暗豎起大拇指。這套模式，實現了文檔編寫後版本管理、發布、存檔、分享的高度自動化，它不僅僅可以應用在文章中介紹的技術文檔發布模式，同樣也適用於我們大多數web、app等軟體生命週期過程模式。DevOps一詞的盛行，絕對不是軟體行業中又一個流行語的鼓吹和炒作，而是軟體過程的一種發展和進化。結合自動化平台、Docker、雲平台等優秀技術和產品、軟體的過程模式將會越來越高效，使得產品的發布周期越來越密集、資訊技術將會對我們的生活便利性發揮出更大的推動力。

在仔細閱讀和分析分析了文章中的相關內容，因文章中提到TFS、持續整合、Azure等都比較熟悉，但同時也非常有興趣於文章提到的reST產生過程，於是著手驗證和體驗了一下如何把一個平面文檔產生一個帶導航、有組織、體檢良好的使用者文檔。

下面是把rst文檔產生為html的工具配置和組織相關文檔的過程記錄。

1， 下載安裝Python

2， 下載Python包SetupTools

檢查Python目錄下的子目錄Scripts是否存在easy_install.exe檔案，如果存在請繼續第三步，不存在請下載https://pypi.python.org/pypi/setuptools zip包，解壓後放到Python安裝的根資料夾下面，並該目錄加入到環境變數中。

3， 安裝Sphinx

啟動CMD，並運行命令”easy_install sphinx”，該過程需要一段時間，安裝過程中有warning，並長時間等待時，可以按鍵盤的任意鍵，繼續運行，直到安裝完成。

 

 

4， 準備rst文檔及相關目錄

目錄結構包含如下，其中docs檔案夾包含rst檔案。Conf.py存放sphinx-build命令的相關參數，可以根據模板自己文檔內容進行修改。

 

 

該樣本,在docs檔案中存放了一個檔案index.rst，內容如下：

 

 

5， 構建rst文檔

在rst文檔所在的項目目錄下運行cmd，運行“sphinx-build -b html ./docs/ ./build/”

運行結果如下，出現無法匯入sphinx_rtd_theme 模組異常資訊。

 

 

6， 安裝sphinx_rtd_theme

在cmd中運行“pip install sphinx_rtd_theme”，安裝相應的模組。

 

 

7， 再次構建rst文檔，產生html文檔

 

 

8， 構建結果

在rst文檔中的build目錄中產生了根據rst文檔建立的html及相關文檔。

 

Python sphinx-build在Windows系統中產生Html文檔