使用 Sphinx 將個人筆記變成文檔的形狀~

本文從記錄筆記和後期歸檔出發，對比了多個平臺記錄筆記的特點和優勢，最後詳細記錄了使用 Sphinx 編譯筆記為 html 的例子。

搭建過程從第二部分開始

需求分析 & 平臺對比

首先關於為什麼選用 Sphinx 編譯筆記和文檔，Hexo 和 gitbook 也挺香的。Sphinx 是綜合對比下的選擇。

首先是 Typora，它簡直就是寫 md 的神器，寫 md 的同時還能預覽，沒有大部分 md 編輯器左邊寫 md 右邊預覽的那種割裂感。但只適合單個文檔的編輯，如果加上多標籤那就完美了。有時大概有印象要找的內容在某篇筆記中，但沒法全局搜索就有些麻煩。

然後有朋友推薦了 gitnote，雖然它可以多標籤頁編輯多個 md 了，但問題同樣是顯著的 —— 慢且默認為 md 編輯模式，預覽還得多切換一次。慢是說它每次啟動都得卡半天（已經安裝在固態盤中），且經常會有高 CPU 和磁碟佔用，可能會定時掃描文件變動實現版本管理。

也參考了朋友的意見使用 Trello 記錄筆記，但感覺它更多是針對工作流的，對於個人筆記而言好像又太複雜了。

至此我的需求大致明確，平常記錄筆記使用 md；後期方便查閱和搜索；查閱和搜索時秒開；最好有多標籤，沒有也可以；最後，編譯出來的顏值要夠。因而將目標轉向了將 md 文件編譯為 html 的一些框架，編輯和整理時通過 Typora 書寫，查閱時可以通過網頁的形式全局搜索。

gitbook 和 Hexo 等框架可以很方便的將 md 文件編譯為 html，但 gitbook 編譯出的 html 需要掛在 Nginx 上，不然沒法跳轉；hexo 雖然沒有上述缺點，但它是針對 blog 的框架，不太適合筆記。因而最終選定了 Sphinx，靜態網頁且夠快夠好看。

使用 Nginx 掛載 gitbook 編譯的連結可以參考我以前的推文：開發文檔加載不再卡頓，億點點提升

使用 Sphinx 記筆記環境搭建

首先安裝必要的包，我用的 python 環境是 Anaconda，日常不激活 conda 環境而是直接用。安裝包用匹配即可，用 conda 管理環境反而麻煩（在不需要做環境隔離的情況下）。

pip install sphinx sphinx_rtd_theme sphinx-autobuild pip3 install recommonmark sphinx_markdown_tables
首先安裝本體和一個主題，還有一個自動編譯的工具。第二行安裝了兩個插件，添加了對 md 文件的支持。
框架搭建
在一個空目錄下運行 sphinx-quickstart，輸出的信息大致如下，除了最後的語言注意填寫 zh_CN，其他的幾個隨便填，後面可以改。

生成文件後有一些奇奇怪怪的文件，需要關注的有兩個
conf.py：Sphinx 的配置，設置插件主題等
打開 conf.py，修改主題，添加插件，找到相關的內容改成這樣。還可以添加其他的插件實現其他的效果和功能，sphinx_rtd_theme 主題比較好看，有其他顏值高的主題求推薦一波。
extensions = [	'recommonmark',	'sphinx_markdown_tables']
html_theme = 'sphinx_rtd_theme'
至此，可以在有 make.bat 或者 Makefile 的目錄下運行 make html 編譯文檔，編譯出來的文件在 build\html 目錄下。
可以使用 sphinx-autobuild 命令自動編譯，可以實時刷新寫好的文檔，但是文檔有錯誤時不會顯示報錯信息。會在 localhost 的某個埠掛載編譯好的靜態 html，並實時刷新。
sphinx-autobuild source build/html
編寫自己的文檔和筆記
sphinx 用的是一套叫 reStructuredText 的純文本標記語法，功能比 md 更豐富，語法參考連結。
不過寫文檔可以不用太了解 rst 的語法，打開 index.rst，結構大致如下
toctree 的三個空格很重要，少了都報錯，最下面的是參考連結，可以不要。
這是標題=============================
可以寫點什麼東西
.. toctree::   :maxdepth: 2   :caption: 目錄標題:      about   test/testfile


這也是標題==================
* :ref:`genindex`* :ref:`modindex`* :ref:`search`
在 index.rst 的 toctree 下面加入自己寫的內容後要建立對應的文件
mkdir testtouch about.mdtouch test\testfile.md
由於之前安裝的 recommonmark 插件，可以愉快的使用 md 寫文檔了。
可以把下面的內容粘貼到新建的 md 中，方便編譯測試
最終完成的效果，奇怪的筆記文檔增加了。
使用 Sphinx 編譯自己的筆記文檔還挺簡單的，但是沒搞明白之前還是挺蛋疼的，參考了一些連結但感覺還是寫的不是太清楚，故我自己總結一下。
問題和改進中文路徑
目前出現了文檔中存在中文路徑時無法正常讀取圖片的 bug，猜測是轉義出了問題，不過沒有修復完成。
風格主題
現在使用的主題還有一點不太滿意，代碼高亮風格和其他的一些細節想改改，後續可能會研究研究怎麼修改。
一文多發
眾所周知 md 是最好的純文本標記語言（狗頭），csdn、知乎、公眾號或者其他平臺都支持 md 格式的文檔。唯一的問題就是在本地環境下圖片是相對路徑，輾轉到各個平臺還得重新上傳圖片。一個解決辦法是使用圖床，將文檔內的圖片替換為外鏈後就可以多個平臺複製粘貼發送一氣呵成。
參考連結