參加的數據科學班今天結束了歉闰，但還有很多疑難點沒搞清楚，很多收獲也沒整理舍杜。課程結束后想補寫下筆記，做下查遺補漏赵辕，心想既绩，與其寫筆記，不如寫成一本書的形式还惠，更美觀饲握，也更系統(tǒng)。
現有的寫電子書的方式蚕键，有以下幾個解決方案救欧，優(yōu)劣勢也很明顯。
- 自有博客锣光，跟散文堆在一起笆怠，不便索引。
- GitHub Wiki誊爹，適合做知識整理蹬刷，但排版一般，不方便本地查看频丘。
- GitBook办成，丑，慢搂漠。
經過一些比較和調查迂卢，最終鎖定 Sphinx + GitHub + ReadtheDocs 作為文檔寫作工具。用 Sphinx 生成文檔桐汤，GitHub 托管文檔而克，再導入到 ReadtheDocs。
Sphinx 是一個基于 Python 的文檔生成工具怔毛，最早只是用來生成 Python 官方文檔拍摇，隨著工具的完善，越來越多的知名的項目也用他來生成文檔馆截，甚至完全可以用他來寫書充活，我最初被他所震撼蜂莉，也是因為看到了這本書 Linux 工具教程。
引用幾點 Sphinx 的優(yōu)勢：
- 豐富的輸出格式: 支持 HTML (包括 Windows 幫助文檔), LaTeX (可以打印PDF版本), manual pages（man 文檔）, 純文本
- 完備的交叉引用: 語義化的標簽,并可以自動化鏈接函數,類,引文,術語及相似的片段信息
- 明晰的分層結構: 可以輕松的定義文檔樹,并自動化鏈接同級/父級/下級文章
- 美觀的自動索引: 可自動生成美觀的模塊索引
- 精確的語法高亮: 基于 Pygments 自動生成語法高亮
更多介紹混卵，請看此處：Sphinx 使用手冊映穗。
注：以下操作默認你熟悉命令行操作。
1. 安裝 Sphinx
Mac 系統(tǒng)下安裝極簡幕随，一行代碼搞定
brew cask install sphinx
或
pip install sphinx
我因為之前安裝過 Anaconda蚁滋，自帶了 sphinx，便省略這步了赘淮。更多安裝方法辕录，請看此處：Install Sphinx。
2. 創(chuàng)建工程
創(chuàng)建工程也就是創(chuàng)建文檔梢卸。這步很簡單走诞，進入需要創(chuàng)建工程的目錄，比如我的是 /Users/Scott/Documents/2.創(chuàng)造樂趣, 創(chuàng)建一個名為 DataBook 的文件夾蛤高，你可以用別的你想用的名字蚣旱。
創(chuàng)建：
? 2.創(chuàng)造樂趣 pwd
/Users/Scott/Documents/2.創(chuàng)造樂趣
? 2.創(chuàng)造樂趣 mkdir BookData
? 2.創(chuàng)造樂趣 ls
1.keynote 2.技術 BookData 映射
BookData 創(chuàng)建好了，進入該目錄：
? 2.創(chuàng)造樂趣 cd BookData
輸入sphinx-quickstart戴陡，接下來程序會提示你輸入一些選項塞绿，基本上按 Return 就好了，有些地方看提示注意下恤批，不懂的話可以參考這里：建立sphinx工程异吻。
完成之后，
? BookData git:(master) ? ls
Makefile build make.bat source
可以看到有4個文件：
- build 目錄 運行make命令后喜庞，生成的文件都在這個目錄里面
- source 目錄 放置文檔的源文件
- make.bat 批處理命令
- makefile
基本完成涧黄，使用 make html 命令就可以生成html形式的文檔了。
配置（conf.py）
如果沒有什么特殊需要赋荆，我覺得 Sphinx 沒啥好配的笋妥，改個主題就好了，個人極其喜歡ReadtheDoc的主題窄潭。很簡單春宣，把 conf.py 里面的這句：
html_theme = 'alabaster'
換成
html_theme = 'sphinx_rtd_theme'
將 Sphnix 生成的文檔和配置 push 到遠程 github
? BookData git init
? BookData git add .
? BookData git commit -m "sphinx start"
? BookData git remote add origin https://github.com/[yourusename]/[yourrepository].git
? BookData git push origin master
注意：[yourusename]/[yourrepository] 換成你的 github 名和倉庫名。
3. 導入到 ReadtheDocs
GitHub 里選擇倉庫嫉你，然后依次點擊 Setting => Webhooks & Service => Add service => ReadTheDocs,激活這個選項月帝。
到 ReadtheDocs import 這個倉庫，導入成功后幽污，點擊閱讀文檔嚷辅，便可看到 Web 效果了。
4. 配置目錄結構
到了這一步距误，基本上已經搭建了簸搞，但這個時候直接寫文檔是還不夠的扁位。目錄結構需要配置下。
假如我要添加兩個文檔 example.rst 和 rest_eazy.rst 到索引 index.rst 里：
.. toctree::
:maxdepth: 2
example
rest_eazy
make html后趁俊，效果如下：
會發(fā)現明明是2個文檔域仇，左邊卻 有 3個標題，因為主索引是按一級標題的數量來索引的寺擂，所以這種方式不可取暇务，標題一多會很亂，好的辦法是創(chuàng)建二級索引：
因為我要建的板塊是3個怔软，分別為數據科學「入門篇」垦细、「基礎篇」、「工具篇」挡逼，所以先把主索引 index.rst 改為：
目錄:
^^^^^
.. toctree::
:maxdepth: 2
:glob:
beginning/index
base/index
tool/index
然后在 source 目錄下創(chuàng)建 3個目錄 括改，每個目錄下創(chuàng)建一個 index.rst 文件，也就是二級索引文件挚瘟。
mkdir beginning base tool
touch beginning/index.rst base/index.rst tool/inde.rst
做完這步后叹谁，把書的大綱理一下饲梭，寫到 BookData 目錄底下的 README.md 文件里：
# Python 和數據科學
### 全書目錄：
入門篇：
- Linux
- ipython
- 數值計算（Numpy）
- 數據繪圖（Matplotlib）
- 數據繪圖（Seabornd)
參照目錄創(chuàng)建文件乘盖，如 入門篇，則在 beginning 目錄下創(chuàng)建如下文件：
touch 01_linux.rst 02_ipython.rst 03_numpy.rst 04_matplotlib.rst 05_seaborn.rst
每個文件里寫上 一級標題憔涉，然后檢查下：
? BookData git:(master) ? ls source/beginning
01_linux.rst 03_numpy.rst 05_seaborn.rst
02_ipython.rst 04_matplotlib.rst index.rst
? BookData git:(master) ? cat source/beginning/*
Linux 基礎
=========================
Jupyter 基礎
=========================
數值計算（Numpy）
=========================
數據繪圖（Matplotlib）
=========================
數據繪圖（Seaborn)
=========================
然后把文件名添加到二級索引 beginning/index 里
入門篇
==========
這一部分主要介紹數據科學的入門內容;\
包含數據科學的基礎工具订框，如：Jupyter、Linux兜叨，以及 Python 基本的數據科學包 Numpy穿扳，畫圖包 Matplotlib;
.. toctree::
:maxdepth: 2
:numbered: 2
01_linux
02_ipython
03_numpy
04_matplotlib
05_seaborn
同理于 base 和 tool 目錄，都完成之后會是下圖的效果：
鏈接：BookData国旷， 有三個索引矛物，下一個，上一個都非常順暢跪但。
其他
reStructureText 語法很簡單履羞，不建議刻意去學，如果習慣用 Markdown屡久，建議用 pandoc 一鍵轉化即可.
