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

簡(jiǎn)介

1 ?reStructuredText是什么？

reStructuredText是擴(kuò)展名為.rst的純文本文件，含義為”重新構(gòu)建的文本“，是python編程語(yǔ)言的Docutils項(xiàng)目的一部分。.rst文件是一種輕量級(jí)標(biāo)記語(yǔ)言，與html的復(fù)雜結(jié)構(gòu)相比，它的設(shè)計(jì)對(duì)人更加友好，被設(shè)計(jì)為容易閱讀和編寫的純文本，并且可以借助Docutils這樣的程序進(jìn)行文檔處理，也可以轉(zhuǎn)換為html或pdf等多種格式，或由Sphinx這樣的程序轉(zhuǎn)換為man手冊(cè)等更多格式

2 ?sphinx是什么？

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

環(huán)境搭建

1 ?搭建Python環(huán)境

sphinx和reStructuredText是python編程語(yǔ)言的一部分，所以需要先配置好Python環(huán)境。 在Python的官方網(wǎng)站下載安裝程序按默認(rèn)選項(xiàng)安裝即可，默認(rèn)安裝路徑C:\python27 需要注意的是根據(jù)你的主機(jī)是32位還是64位來選擇下載哪個(gè)進(jìn)行安裝

2 ?安裝setuptools

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

進(jìn)入dos窗口，執(zhí)行以下命令安裝setuptools cd C:\python27 C:\python27\python.exe ez_setup.py

3 ?安裝sphinx

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

4 ?設(shè)置環(huán)境變量

設(shè)置環(huán)境變量的作用是讓你在輸入命令的時(shí)候不需要在輸入完整的路徑，只要輸入命令名稱即可。 在桌面右擊計(jì)算機(jī)->屬性->高級(jí)系統(tǒng)設(shè)置->環(huán)境變量，選擇系統(tǒng)變量的path項(xiàng)點(diǎn)擊編輯，增加以下兩個(gè)路徑 ;C:\python27;C:\python27\scripts

需要注意的是每個(gè)路徑都是以英文的分號(hào)來分割，我們添加了兩個(gè)路徑，在這兩個(gè)路徑之間需要用“;”分開，另外，在第一個(gè)路徑之前也需要增加一個(gè)“;”，與原有的路徑進(jìn)行區(qū)分
到此為止，windows下搭建sphinx+reStructuredText的工作就全部完成了。 下一節(jié)我們以一個(gè)簡(jiǎn)單的實(shí)例來展示它的強(qiáng)大功能

使用實(shí)例

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

運(yùn)行該命令會(huì)提示很多是選項(xiàng)，我們只需要在project Name后寫上自己的工程名稱，Authors Name后寫上作者名稱，其他的按默認(rèn)即可 命令結(jié)束后會(huì)在sphinx-test目錄下生成以下幾個(gè)文件


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

出現(xiàn)上面的效果說明轉(zhuǎn)換html通過，會(huì)在該目錄_build目錄下生成響應(yīng)的html文件，我們進(jìn)入目錄下的_build/html，使用瀏覽器打開index.html，查看頁(yè)面效果

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


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


OK，剩下的工作就是好好學(xué)習(xí)reStructuredText語(yǔ)言，然后不斷的make.bat html和查看頁(yè)面進(jìn)行調(diào)試了，注意rst文件編寫如果不符合規(guī)則，make.bat的時(shí)候會(huì)提示報(bào)錯(cuò)信息，按照?qǐng)?bào)錯(cuò)信息修改對(duì)應(yīng)文件的對(duì)應(yīng)行即可

推薦學(xué)習(xí)網(wǎng)站：http://jwch.sdut.edu.cn/book/rst.html，這個(gè)是reStructuredText的簡(jiǎn)明教程，這個(gè)網(wǎng)站本身也是reStructuredText編寫的，我們可以通過點(diǎn)擊頁(yè)面左側(cè)的show source查看右側(cè)窗口的源碼，比對(duì)源碼與頁(yè)面顯示，學(xué)習(xí)更有效率

?

轉(zhuǎn)載于:https://www.cnblogs.com/gordon0918/p/5280590.html

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。