最近有朋友想在windows下做個人筆記，沒有找到順手的工具，問我有什么好的工具推薦。正好前兩天在網上看到一款做文檔的利器sphinx+reStructText，當時在ubuntu下搭了下環境試了試，做筆記真的非常方便。今天在windows下試了試，遇到一些問題，但總算成功了，現整理如下。

簡介

1 ?reStructuredText是什么？

reStructuredText是擴展名為.rst的純文本文件，含義為”重新構建的文本“，是python編程語言的Docutils項目的一部分。.rst文件是一種輕量級標記語言，與html的復雜結構相比，它的設計對人更加友好，被設計為容易閱讀和編寫的純文本，并且可以借助Docutils這樣的程序進行文檔處理，也可以轉換為html或pdf等多種格式，或由Sphinx這樣的程序轉換為man手冊等更多格式

2 ?sphinx是什么？

Sphinx 是一種工具，它允許開發人員以純文本格式編寫文檔，以便采用滿足不同需求的格式輕松生成輸出。它使用 reStructuredText標記語法來提供文檔控制，可以將 Sphinx想像成為一種文檔框架：它會抽象化比較單調的部分，并提供自動函數來解決一些常見問題，比如突出顯示標題索引和特殊代碼（在顯示代碼示例時），以及突出顯示適當的語法

環境搭建

1 ?搭建Python環境

sphinx和reStructuredText是python編程語言的一部分，所以需要先配置好Python環境。 在Python的官方網站下載安裝程序按默認選項安裝即可，默認安裝路徑C:\python27 需要注意的是根據你的主機是32位還是64位來選擇下載哪個進行安裝

2 ?安裝setuptools

setuptools是python的一個增強工具，我們安裝模塊式常用的easy_install命令就是setuptools中的一個工具；
去官方網站下載ez_setup.py，如下圖所示，右擊->目標另存為，將ez_setup.py下載到本地
然后將ez_setup.py放到python的安裝目錄C:\python27，如下圖所示

進入dos窗口，執行以下命令安裝setuptools cd C:\python27 C:\python27\python.exe ez_setup.py

3 ?安裝sphinx

安裝完setuptools，我們就是可以只用其中的easy_install命令很簡單的安裝sphinx模塊 進入dos界面，輸入以下命令 C:\python27\easy_install.exe sphinx

4 ?設置環境變量

設置環境變量的作用是讓你在輸入命令的時候不需要在輸入完整的路徑，只要輸入命令名稱即可。 在桌面右擊計算機->屬性->高級系統設置->環境變量，選擇系統變量的path項點擊編輯，增加以下兩個路徑 ;C:\python27;C:\python27\scripts

需要注意的是每個路徑都是以英文的分號來分割，我們添加了兩個路徑，在這兩個路徑之間需要用“;”分開，另外，在第一個路徑之前也需要增加一個“;”，與原有的路徑進行區分
到此為止，windows下搭建sphinx+reStructuredText的工作就全部完成了。 下一節我們以一個簡單的實例來展示它的強大功能

使用實例

首先在桌面建立一個空文件夾sphinx-test，在dos下進入該目錄，執行以下命令 cd C:\Users\xlzh\Desktop\sphinx-test sphinx-quickstart

運行該命令會提示很多是選項，我們只需要在project Name后寫上自己的工程名稱，Authors Name后寫上作者名稱，其他的按默認即可 命令結束后會在sphinx-test目錄下生成以下幾個文件


我們要編輯的就是其中的index.rst，首先我們先不著急編輯，先看一下默認的效果 進入dos窗口，進入shpinx-test目錄，執行以下命令 cd C:\Users\xlzh\Desktop\sphinx-test make.bat html

出現上面的效果說明轉換html通過，會在該目錄_build目錄下生成響應的html文件，我們進入目錄下的_build/html，使用瀏覽器打開index.html，查看頁面效果

以上顯示是默認的頁面，現在讓我們回過頭來用記事本打開index.rst并進行編輯，增加幾行代碼，展示自己的東西，如下所示


需要注意的是此時的index.rst是ANSI編碼的，不支持漢字，需要點擊文件->另存為，保存為utf-8格式，覆蓋原文件即可 修改完畢，再次運行命令 make.bat html
刷新剛才的頁面看下效果吧


OK，剩下的工作就是好好學習reStructuredText語言，然后不斷的make.bat html和查看頁面進行調試了，注意rst文件編寫如果不符合規則，make.bat的時候會提示報錯信息，按照報錯信息修改對應文件的對應行即可

推薦學習網站：http://jwch.sdut.edu.cn/book/rst.html，這個是reStructuredText的簡明教程，這個網站本身也是reStructuredText編寫的，我們可以通過點擊頁面左側的show source查看右側窗口的源碼，比對源碼與頁面顯示，學習更有效率

?

轉載于:https://www.cnblogs.com/gordon0918/p/5280590.html

總結

以上是生活随笔為你收集整理的Windows下配置sphinx+reStructuredText详解的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。