我們從小開始接觸計(jì)算機(jī)的方式就讓我們陷入了一種怪圈兒，比如操作系統(tǒng)只會(huì)用Windows、碼字只知道word而且相信大多數(shù)人到現(xiàn)在依然還用不好、處理簡(jiǎn)單的文本表格只知道用excel。這些工具當(dāng)然很好，也很強(qiáng)大，而且使用門檻低，也是廣大人民日常工作中的必備工具。 但是，適用于大多數(shù)人就一定說明了它缺少了很多特性。尤其是對(duì)于科研工作者，這些基礎(chǔ)的工具很難滿足一些特定的需求。今天我就來(lái)介紹一種碼字方式：碼一份字，發(fā)布為多種平臺(tái)(或格式)，而且很美觀！這個(gè)神器就是Sphinx+rst！
什么是RST？
reStructuredText 是擴(kuò)展名為 .rst
的純文本文件，含義為"重新構(gòu)建的文本"，也被簡(jiǎn)稱為：RST 或 reST； 是
Python 編程語(yǔ)言的 Docutils 項(xiàng)目的一部分，Python Doc-SIG (Documentation
Special Interest Group)。 該項(xiàng)目類似于 Java 的 JavaDoc 或 Perl 的 POD
項(xiàng)目。 Docutils 能夠從 Python 程序中提取注釋和信息，格式化成程序文檔。
.rst 文件類似于.md(Markdown)文件，是輕量級(jí)標(biāo)記語(yǔ)言的一種，
被設(shè)計(jì)為容易閱讀和編寫的純文本，并且可以借助 Docutils
這樣的程序進(jìn)行文檔處理， 可以方便地轉(zhuǎn)換為 HTML , Latex, Markdown
等多種格式。
rst在標(biāo)記功能上比md豐富太多了，而且在Sphinx的框架下可以非常方便地使用各種插件，來(lái)實(shí)現(xiàn)各種不同特定需求。
比如地學(xué)領(lǐng)域最常用的繪圖和數(shù)據(jù)處理軟件gmt，其開發(fā)團(tuán)隊(duì)現(xiàn)在已經(jīng)開發(fā)了適用于Sphinx的插件sphinx_gmt，
這個(gè)插件的功能就是可以直接在rst文件中進(jìn)行繪圖，類似于Sphinx內(nèi)置的python繪圖插件.. plot::。
比如在rst文件中寫入如下所示的文字，就可以直接自動(dòng)根據(jù)你的gmt繪圖命令將圖片繪制好并嵌入到最終生成的html文件，或者pdf中，
而不需要先找個(gè)地方運(yùn)行g(shù)mt命令畫圖，然后在把圖片插入到wrod中再導(dǎo)出為pdf。用rst碼字，根本沒有這么多麻煩事兒，全都是自動(dòng)化！
.. gmtplot::
:language: bash
:show-code: false
gmt pscoast -Rg -JW12c -Ba60 -Gblack > globe.ps
這篇文章就是用rst寫的，所以上面說的gmt插件的例子是實(shí)例！
像上面提到的這種插件還是非常非常多的，如果懂一點(diǎn)python編程，還可以根據(jù)自己的需要寫一個(gè)插件。
(其實(shí)這個(gè)gmt的插件，兩年前我已經(jīng)寫出來(lái)了而且在用了，類似的我還寫了tikz的插件，只是自己用沒有公開發(fā)布)
基于rst的基本功能還有這些插件的幫助，學(xué)術(shù)寫作過程中常用的公式編寫、圖-表-公式-列表等交叉引用、參考文獻(xiàn)引用、代碼塊等需求，都是完美解決的！
什么是Sphinx？
Sphinx 是一種文檔工具，它可以令人輕松的撰寫出清晰且優(yōu)美的文檔, 由 Georg
Brandl 在BSD 許可證下開發(fā). 新版的Python文檔就是由Sphinx生成的，
并且它已成為Python項(xiàng)目首選的文檔工具,同時(shí)它對(duì) C/C++ 項(xiàng)目也有很好的支持;
并計(jì)劃對(duì)其它開發(fā)語(yǔ)言添加特殊支持。
除了寫程序項(xiàng)目的文檔之外，還可以用Sphinx寫博客，其實(shí)用它來(lái)寫博士論文都不在話下。
本文當(dāng)然也是使用 Sphinx生成的，它采用reStructuredText! （博客首頁(yè)為:
https://www.scibyte.cn/blog/zh/blog.html)
所以，Sphinx和rst有著不可分割的關(guān)系。
可以這么理解：Sphinx是一個(gè)Python寫的程序，可以使用Python寫配置及插件，將rst標(biāo)記的文檔生成各種優(yōu)美的格式。
其特性如下：
-
豐富的輸出格式: 支持 HTML (包括 Windows 幫助文檔), LaTeX
(可以打印PDF版本), manual pages（man 文檔）, 純文本 -
完備的交叉引用:
語(yǔ)義化的標(biāo)簽,并可以自動(dòng)化鏈接函數(shù),類,引文,術(shù)語(yǔ)及相似的片段信息 -
明晰的分層結(jié)構(gòu):
可以輕松的定義文檔樹,并自動(dòng)化鏈接同級(jí)/父級(jí)/下級(jí)文章 - 美觀的自動(dòng)索引: 可自動(dòng)生成美觀的模塊索引
- 精確的語(yǔ)法高亮: 基于 Pygments 自動(dòng)生成語(yǔ)法高亮
-
開放的擴(kuò)展: 支持代碼塊的自動(dòng)測(cè)試,并包含Python模塊的自述文檔(API
docs)等 - Sphinx 使用 reStructuredText 作為標(biāo)記語(yǔ)言,
可以享有Docutils為reStructuredText提供的分析，轉(zhuǎn)換等多種工具.
如何實(shí)現(xiàn)多平臺(tái)部署
上面已經(jīng)講了Sphinx和rst的特性，可以將同一份rst文檔，生成各種不同的格式以供不同的平臺(tái)發(fā)布。
下面我將重點(diǎn)介紹一下rst->網(wǎng)頁(yè)博客->公眾號(hào)圖文的效果。
網(wǎng)頁(yè)平臺(tái)
Sphinx最大的特性就是自定義格式，比如生成的網(wǎng)頁(yè)html文件，可以自定義html的模板和樣式(css)。
比如我的博客，就是自己用Sphinx寫的。
每次寫完一篇博文的rst文件然后只需要運(yùn)行一個(gè)幾行簡(jiǎn)單的命令，就可以完成生成html到網(wǎng)絡(luò)服務(wù)器的部署，那是相當(dāng)?shù)氖∈聝海?br>
比如一個(gè)操作示例用下面的動(dòng)畫表示：
動(dòng)畫鏈接
網(wǎng)頁(yè)博客示例
微信公眾號(hào)
自己的博客自己做主，各種樣式都可以自己定義，這也是最輕松的。
但是如果想將同一篇博文也發(fā)布到微信公眾號(hào)里面，一般情況下還是非常費(fèi)勁的，誰(shuí)排版過微信誰(shuí)知道其中的酸爽！
其實(shí)如果我們用rst寫完一篇博文，根本不需要用什么秀米啥的排版搞半天，基本上可以用代碼分分鐘搞定微信公眾號(hào)上的排版。
基本上以下幾個(gè)步驟：
- 將rst轉(zhuǎn)換為md(Markdown):
pandoc xxx.rst -o xxx.md - 解決md里面涉及到的交叉引用和代碼塊等格式問題，我已經(jīng)寫了相應(yīng)的小程序:
python post2md.py xxx.rst - 使用一款非常有情懷非常強(qiáng)大還開源的markdown轉(zhuǎn)微信公眾號(hào)的工具markdownnice，直接將上面轉(zhuǎn)換好的md復(fù)制到這個(gè)工具中，點(diǎn)擊復(fù)制微信公眾號(hào)按鈕，然后直接粘貼到微信公眾號(hào)的圖文里面就得到相應(yīng)的效果（就像本文）。
唯一需要注意的是，為了使微信公眾號(hào)發(fā)文在一分鐘內(nèi)搞定，那rst文件中的圖片必須使用自定義的圖床來(lái)解決，否則圖片可能會(huì)無(wú)法上傳到公眾號(hào)里面。
這個(gè)是無(wú)法改變的，它就是那樣！
Latex或PDF
在大多數(shù)情況下我們都有生成pdf文件的需求，比如開發(fā)了一款學(xué)術(shù)軟件，在投稿的時(shí)候，期刊要求提供說明文檔或者操作手冊(cè)。
這東西用Sphinx編寫簡(jiǎn)直再好不過了，是需要用簡(jiǎn)單的一個(gè)命令
make latex 就可以生成文檔的latex所有文件，
然后到latex文件的目錄運(yùn)行一個(gè)命令 make
就可以生成pdf文件。 幾乎是分分鐘的事兒，操作過程如下面的動(dòng)畫所示。
其他
除了常用的html和pdf格式，sphinx還可以生成電子書epub格式，還有man格式。
還有一些別的，可以自行研究了。
