用Sphinx寫日記

來自專欄 Hacky Teddy4 人贊了文章

英文博文：Write a Diary with Sphinx

Ted最喜歡的輕量級標記語言非 reStructuredText [1] 莫屬。和XML/HTML不同，輕量級標記語言更適合人閱讀，但同時也保留了一定的超文本標記功能。如今有很多靜態網站生成器（例如Jekyll, Nikola）就使用了輕量級標記語言。雖然reST比不上Markdown [2] 有名，在我看來，它功能更加強大，以及更具有可擴展性（比如自定義指令）。Python的官方文檔 [3] 也是用它來撰寫的，再通過Sphinx [4] 這個文檔生成器生成出HTML輸出。Sphinx則是調用了docutils [5] 這個更底層的庫來parse reST格式的輸入。

通常來說，文檔生成器大多用來產生一個項目的代碼所對應的參考手冊和教程。然而，得益於Sphinx的通用功能，我們也可以用它來寫日記！接下來Ted會簡單介紹如何用一個Sphinx 項目來管理編譯多個日記本。

快速上手

第一件事情當然是安裝Sphinx了。以Archlinux為例，只需執行以下命令即可：

sudo pacman -S python-sphinx

接著我們可以利用「快速開始」工具來創建一個樣板工程：

sphinx-quickstart diaries

這條命令會開始一個類似安裝嚮導的過程，並詢問你若干個問題來完成基本的配置。假設你大部分按照的是默認設置，項目目錄最後會像這樣：

>> cd diaries/** 02:28:50 /t/diaries ymf@Pixelbook **>> ls -ltotal 16drwxr-xr-x 2 ymf ymf 40 Jun 22 02:28 _build-rw-r--r-- 1 ymf ymf 4723 Jun 22 02:28 conf.py-rw-r--r-- 1 ymf ymf 449 Jun 22 02:28 index.rst-rw-r--r-- 1 ymf ymf 607 Jun 22 02:28 Makefiledrwxr-xr-x 2 ymf ymf 40 Jun 22 02:28 _staticdrwxr-xr-x 2 ymf ymf 40 Jun 22 02:28 _templates

我們可以在index.rst中加入我們的日記文件，其中每個文件包含一個日記本的內容。在index.rst中保存如下內容：

My Memories===========.. toctree:: :maxdepth: 2 life researchIndices and tables==================* :ref:`genindex`* :ref:`modindex`* :ref:`search`

你應該猜到了，我們也應該相應地在目錄下增加兩個reST文件：life.rst和research.rst。life.rst：

My Life=======Day 1-----I met a nice girl. Her name is Daisy.Day 2-----We had dinner together and went to a movie.Day 3-----I showed my love to her because I couldt resist myself. She smiled and replied, "Youre such a nice guy, but...its not working out."Day 4-----Sad and depressed, I choose to die. This is my last diary.

research.rst：

The Road of PhD===============Day 1-----I got the offer!Day 2-----The first day in the lab is great. Day 3-----Still dont have a paper.Day ∞-----Still dont have a paper...

最後，嘗試編譯你的日記：

make html

上面的命令會生成HTML輸出到 _build/html目錄。用瀏覽器打開即可查看日記：

點擊"My Life"的連結就會跳到日記內容的頁面：

折騰

目前看來一切正常。用reST中的章節來表示每一篇日記是個不錯的idea，因為實際上一個人也寫不了太多的日記。假設一天寫10篇日記，並且堅持寫100年，那麼總共章節的數目也不過365000篇左右，按理說可以被現代的瀏覽器高效地顯示出來（Ted瞎猜的）。所以可擴容性不是個大問題。當它成為問題的時候，你只需要把日記分割到不同的文件裏就好了，比如按照年份來。

然而這麼記日記有個缺點：日記的順序。一般人都習慣於在文件末尾加入新的內容。試想一天結束準備寫篇日記，一般都會接在原文件的末尾新開一個章節，開始撰寫。然而docutils卻只會按照章節的順序從前到後地生成HTML。我們希望看到的是最新的日記內容可以顯示在頂端，然後依此類推。這樣就不用每次查看最近的內容都要拖到頁底，或者改變reST文檔中章節的順序（日記本最後可以很長呢）。幸運的是，Ted已經給懶人們提供好了hack來改變章節在HTML內容和索引中的順序。添加以下代碼到conf.py末尾：

# reverse the order of sectionsreversed = {"life", "research"}def reverse_sections(app, doctree, docname): if docname in reversed: for node in doctree.traverse(): if node.tagname == "document": l = node[0] children = [] while len(l) > 1: children.append(l.pop()) for c in children: l.append(c)def reverse_tocs(app, env): for docname in reversed: l = env.tocs[docname][0][1] l.children.reverse()def setup(app): app.connect("doctree-resolved", reverse_sections) app.connect("env-updated", reverse_tocs)