關於製作文檔和筆記這種事，我已經糾結了很久，網上解決方案也一大推，我試過幾樣，ScrapBook 和 Zotero，編輯不太方便，同步麻煩。Google Note 過於格式簡單，現在也不更新了，Google Docs又有點殺雞用牛刀。還有傳得很神奇的 Evernote 跟 Onenote，我壓根沒興趣去用。
因為我的筆記大多都是自己寫出來，整理出來的，就是精簡成自己能看得懂的幾段文字而已。我的要求無非這幾樣：主要是純文本、工具開源、能同步和備份。
選擇純文本保存，我需要一個預定義格式，讓筆記看起來有模有樣，編輯器還能有簡單代碼高亮的，於是我在這個輕量級標記語言的維基頁面觀望好久。
Wiki也是一種不錯方案，但是要搭伺服器，不用伺服器的也免不了各種配置，各種wiki系統的格式也不同。又研究了reStructuredText，發現閱讀性非常好，能轉換的格式也非常多。
vim就默認支持代碼高亮了（rst擴展名），也能通過rst2html命令轉換成的html，但是樣式不太理想，我想應該有更漂亮的html生成器。於是我發現Sphinx這個工具，又當我發現其實這就是Python官方文檔解決方案后。
我就做出最後決定了這一組合，reStructuredText作為標記語言，Sphinx作為生成工具。
先來看看reStructuredText格式在vim的效果
生成html效果，就是python風格！
只需安裝python和sphinx即可。 安裝python-sphinx這個包即可，自動解決依賴了，如果追新，則可以通過pypi來安裝（也就是easy_install命令啦，不過要手動安裝幾個依賴庫）。
安裝后，應該會有sphinx-quickstart這個命令了。先新建一個空目錄，這個目錄會放置你的筆記
muzuiget:~$ mkdir note muzuiget:~$ cd note/ muzuiget:~/note$ sphinx-quickstart
會問你N個問題，一般來說，只需要填四個地方，其餘的都直接回車就行了
加粗的是我填的，最後的兩個發布號跟先跟版本號一樣就行了，這個可以以後再改的。然後這個目錄的內容就是這樣
muzuiget:~/note$ tree . . |-- _build |-- conf.py |-- index.rst |-- make.bat |-- Makefile |-- _static `-- _templates 3 directories, 4 files
然後你可以用文本編輯器打開 index.rst 這個文件，如果用vim，就發現有代碼高亮啦。暫時不用改什麼，接著運行
muzuiget:~/note$ make html
然後用瀏覽器打開 _build/html/index.html 你會看到，舒服漂亮的python式文檔出現鳥。
當然現在什麼內容也沒有，現在你就可以向 index.rst 添加內容就行了。 至於reStructuredText的語法，reStructuredText、Sphinx、Python都有簡單的教程
這幾個鏈接的html本身就是reStructuredText寫出來的，比如第一個鏈接的源代碼，另存到為 quickstart.rst，放到 index.rst 的統一目錄下。然後修改 index.rst，就加一行
.. toctree:: :maxdepth: 2 quickstart.rst
注意“quickstart.rst”中的“q”和“ :maxdepth: 2”的冒號在同一列，保存，然後重新
muzuiget:~/note$ make html
再次刷新 _build/html/index.html，你就看到新的內容了，很簡單吧。除了html外，sphinx也支持其它格式，直接運行make就能看到參數了。
下一步問題就是學習reStructuredText來編寫規範的文檔和筆記了，reStructuredText官方有個快速參考。而可供參考的實際例子更加多了，Sphinx的文檔和Python文檔就是非常規範了，頁面旁邊有個“Show Source”鏈接，還不夠，Sphinx上還有個列表。
其實之前的sphinx-quickstart這個命令主要是創建了了 conf.py 這個文件，裡面就是輸出html或其它格式的配置，可以參考Sphinx文檔來修改，定製性相當得高，還內置幾種主題。這個方面還大家慢慢研究吧。
對了，如何同步呢？還用多想，直接把筆記文件夾扔到Dropbox得了，就這麼簡單。在Bitbucket搭個私有倉庫也行。
[火星人 ] 文檔與筆記利器 reStructuredText 和 Sphinx已經有876次圍觀
