我們從小開始接觸計(jì)算機(jī)的方式就讓我們陷入了一種怪圈兒涌献,比如操作系統(tǒng)只會(huì)用Windows裂问、碼字只知道word而且相信大多數(shù)人到現(xiàn)在依然還用不好、處理簡(jiǎn)單的文本表格只知道用excel。這些工具當(dāng)然很好弓柱,也很強(qiáng)大沟堡,而且使用門檻低,也是廣大人民日常工作中的必備工具矢空。 但是航罗,適用于大多數(shù)人就一定說明了它缺少了很多特性。尤其是對(duì)于科研工作者屁药,這些基礎(chǔ)的工具很難滿足一些特定的需求粥血。今天我就來介紹一種碼字方式:碼一份字,發(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的框架下可以非常方便地使用各種插件茁裙,來實(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)寫出來了而且在用了屯耸,類似的我還寫了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í)用它來寫博士論文都不在話下罢维。
本文當(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文件中的圖片必須使用自定義的圖床來解決,否則圖片可能會(huì)無法上傳到公眾號(hào)里面履肃。
這個(gè)是無法改變的仔沿,它就是那樣!
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格式莱睁。
還有一些別的,可以自行研究了品擎。