Sphinx / reStructuredText

之前曾簡介過了pelican由python 寫成的靜態網頁產生器,這篇文章則是有關另一個類似亦由python寫成,適合來作成如網頁電子書型態的文件資料產生器Sphinx,它也是目前python官方網站上用來呈現其技術文件的架站軟體。

1)安裝Sphinx
如同pelican, Sphinx亦是透過pip 進行安裝,請在CLI文字指令介面下輸入一行,即完成其安裝。當然前提是該電腦環境已有python2以及pip
$ pip install -U Sphinx

2)建立一個使用Sphinx的新專案
建一個專案目錄,透過CLI把目前工作目錄切換到此新專案目錄底下後,輸入以下指令:
$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)功能,個人高度推薦。


0 意見:

Security First: umbrella app 中文化滙整

之前提過會作一篇 Security First's umbrella app 滙整與中文化超連結整合,以讓未下載使用、觀看過原手機應用的讀者(其實指的就是錯亂的我自己本人)稍能有全盤的概念來想像這個手機應用程式(或更精準的說:一個手機上的隨身電子書)的內容。好了,本文...