Sphinx / reStructuredText
之前曾簡介過了pelican由python 寫成的靜態網頁產生器，這篇文章則是有關另一個類似亦由python寫成，適合來作成如網頁電子書型態的文件資料產生器Sphinx，它也是目前python官方網站上用來呈現其技術文件的架站軟體。
1)安裝Sphinx
如同pelican, Sphinx亦是透過pip 進行安裝，請在ＣＬＩ文字指令介面下輸入一行，即完成其安裝。當然前提是該電腦環境已有python2以及pip
$ pip install -U Sphinx
２）建立一個使用Sphinx的新專案
建一個專案目錄，透過ＣＬＩ把目前工作目錄切換到此新專案目錄底下後，輸入以下指令：
$sphinx-quickstart
這時後台會自動來建立相關檔案目錄架構，不過在此同時它會先向你詢問這個專案設定的一些基本問題。我大概都是按「y」(yes)吧，回答完它的一長串問題後，Sphinx就把這個新目錄的資料架構檔案給生出來。
在Sphinx自動生成的一堆檔案中，有一個叫作index.rst檔案，它就是主文件master document，也就是這個專案的「首頁」。從副檔名rst來看，Sphinx使用的是一種叫作「reStructuredText」的文件格式。它一樣可透過純文字編輯器作編寫修改，據說其用法和makrdown相類似，但因其功能更為強大，所以要稍複雜一點。下圖就是index.rst的文件內容。
以我個人摸索sphinx文件結構的少數經驗，建議從沒碰過reStructuredText語法者，可先從這篇：「Sphinx-用reStructuredText 寫網站與書」中的「reStructuredText 的標準語法」段落，尤其是搜尋一下文章中所推薦的eStructuredText 簡易入門一文（原文的連結已經失效了，不過如果透過搜尋引擊還是可以找到這篇出自openfoundry.org的文章），至少先知道怎麼寫標題、作超連結、插入圖片等基本的使用方法即可。
知道了一些最最基本的reStructuredText之後呢，應該會有點信心可以來動手修改透過sphinx-quickstart指令所自動生成的index.rst檔案了。index.rst文件中的文件結構指令「.. toctree::」它有兩個作用，第一個就是告訴 sphinx 檔案是如何被排列組織的；第二個用途是在當前的頁面位置中嵌入目錄。例如我把在toctree加入這三行，代表欲插入三個文章連結。
然後還要在與index同一層目錄下，新增檔名為：preamble.rst, chapter 01.rst, chapter 02.rst 這三個檔案，接下來就可以對文件進行內容的編輯或撰寫。等文件寫好存檔後，只需要將CLI文字指令切換到此專案目錄底下，並輪入$make html ，則shpinx就會自動把rst文件轉換成為html格式，並建立好相對的文件結構目錄（一般是存放在該專案資料夾底下/_build/html/ 底下）。例如我打開這個index.html(是的，sphinx和之前的pelican, hugo, jekyll不太一樣，要看它輸出轉成hmtl的效果直接開啟html檔即可，不必呼叫伺服器指令)，其呈現效果如下：
咦,對照之前index.rst當中在toctree之後放入的文字，怎麼有點不太一樣咧？不一樣之處在於：a)preamble/chapter 01為何在html的首頁中變成了「前言介紹」/「第一條」而且「第一條」底下的子標題居然也一併出現了？ b)怎麼chapter 02的連結沒出現在首頁中呢？如果再看看我的chapter 1.rst 的內文模樣：
因為有依reStructuredText語法，將「第一條」作為文章標題，所以sphinx在將其轉換為html的過程中，就會自動把這個檔案的主標題作為目錄條次。並且因為在toctree之處，我還設定了「maxdepth: 2」，這表示在首頁會呈現二層連結，故chapter 01.rst的子標題「人民自決權」也一併地出現了。同理分析chapter 2.rst的語法結構，因為我並未設定其標題，故在轉換成html的過程中，sphinx雖然也有把該檔案轉換成chapter 2.html,但並不會在首頁為它放入此文章連結。
看看把chapter 2.rst修改放入了文章標題語法，但不加子標題，果然在首頁的顯示就沒出現第二層的子標題。
以上是對Sphinx簡單的介紹，老實說，對於一般人而言，如果要編電子書或是製作網頁型的長篇報告，我可能還是會偏向建議直接透過gitbook平台來操作比較輕鬆，省去了還要再學reStructuredText語法的麻煩。而reStructuredText比較強的優點，可能透過主標題次標題的文件結構自動抓取，適合作長篇式書籍類型的章節層次感展現。
至於其產生的網頁檔以及相關資料，只要透過git或ftp方式，即可上傳佈署到網頁空間上作發表，我就不再重述。例如之前曾介紹過的Pubstorm 就是一個不錯的方式，其免費帳號目前能享有10個網站專案額度，且支援自定的網域名，和不另收費的SSL(Let's encrypted)功能，個人高度推薦。
1)安裝Sphinx
如同pelican, Sphinx亦是透過pip 進行安裝，請在ＣＬＩ文字指令介面下輸入一行，即完成其安裝。當然前提是該電腦環境已有python2以及pip
$ pip install -U Sphinx
２）建立一個使用Sphinx的新專案
建一個專案目錄，透過ＣＬＩ把目前工作目錄切換到此新專案目錄底下後，輸入以下指令：
$sphinx-quickstart
這時後台會自動來建立相關檔案目錄架構，不過在此同時它會先向你詢問這個專案設定的一些基本問題。我大概都是按「y」(yes)吧，回答完它的一長串問題後，Sphinx就把這個新目錄的資料架構檔案給生出來。
在Sphinx自動生成的一堆檔案中，有一個叫作index.rst檔案，它就是主文件master document，也就是這個專案的「首頁」。從副檔名rst來看，Sphinx使用的是一種叫作「reStructuredText」的文件格式。它一樣可透過純文字編輯器作編寫修改，據說其用法和makrdown相類似，但因其功能更為強大，所以要稍複雜一點。下圖就是index.rst的文件內容。
以我個人摸索sphinx文件結構的少數經驗，建議從沒碰過reStructuredText語法者，可先從這篇：「Sphinx-用reStructuredText 寫網站與書」中的「reStructuredText 的標準語法」段落，尤其是搜尋一下文章中所推薦的eStructuredText 簡易入門一文（原文的連結已經失效了，不過如果透過搜尋引擊還是可以找到這篇出自openfoundry.org的文章），至少先知道怎麼寫標題、作超連結、插入圖片等基本的使用方法即可。
知道了一些最最基本的reStructuredText之後呢，應該會有點信心可以來動手修改透過sphinx-quickstart指令所自動生成的index.rst檔案了。index.rst文件中的文件結構指令「.. toctree::」它有兩個作用，第一個就是告訴 sphinx 檔案是如何被排列組織的；第二個用途是在當前的頁面位置中嵌入目錄。例如我把在toctree加入這三行，代表欲插入三個文章連結。
然後還要在與index同一層目錄下，新增檔名為：preamble.rst, chapter 01.rst, chapter 02.rst 這三個檔案，接下來就可以對文件進行內容的編輯或撰寫。等文件寫好存檔後，只需要將CLI文字指令切換到此專案目錄底下，並輪入$make html ，則shpinx就會自動把rst文件轉換成為html格式，並建立好相對的文件結構目錄（一般是存放在該專案資料夾底下/_build/html/ 底下）。例如我打開這個index.html(是的，sphinx和之前的pelican, hugo, jekyll不太一樣，要看它輸出轉成hmtl的效果直接開啟html檔即可，不必呼叫伺服器指令)，其呈現效果如下：
咦,對照之前index.rst當中在toctree之後放入的文字，怎麼有點不太一樣咧？不一樣之處在於：a)preamble/chapter 01為何在html的首頁中變成了「前言介紹」/「第一條」而且「第一條」底下的子標題居然也一併出現了？ b)怎麼chapter 02的連結沒出現在首頁中呢？如果再看看我的chapter 1.rst 的內文模樣：
因為有依reStructuredText語法，將「第一條」作為文章標題，所以sphinx在將其轉換為html的過程中，就會自動把這個檔案的主標題作為目錄條次。並且因為在toctree之處，我還設定了「maxdepth: 2」，這表示在首頁會呈現二層連結，故chapter 01.rst的子標題「人民自決權」也一併地出現了。同理分析chapter 2.rst的語法結構，因為我並未設定其標題，故在轉換成html的過程中，sphinx雖然也有把該檔案轉換成chapter 2.html,但並不會在首頁為它放入此文章連結。
看看把chapter 2.rst修改放入了文章標題語法，但不加子標題，果然在首頁的顯示就沒出現第二層的子標題。
以上是對Sphinx簡單的介紹，老實說，對於一般人而言，如果要編電子書或是製作網頁型的長篇報告，我可能還是會偏向建議直接透過gitbook平台來操作比較輕鬆，省去了還要再學reStructuredText語法的麻煩。而reStructuredText比較強的優點，可能透過主標題次標題的文件結構自動抓取，適合作長篇式書籍類型的章節層次感展現。
至於其產生的網頁檔以及相關資料，只要透過git或ftp方式，即可上傳佈署到網頁空間上作發表，我就不再重述。例如之前曾介紹過的Pubstorm 就是一個不錯的方式，其免費帳號目前能享有10個網站專案額度，且支援自定的網域名，和不另收費的SSL(Let's encrypted)功能，個人高度推薦。
