Sphinx和rst在科研筆記和學(xué)術(shù)博客中的高效用法

我們從小開始接觸計(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)美的格式平窘。
其特性如下:

  1. 豐富的輸出格式: 支持 HTML (包括 Windows 幫助文檔), LaTeX
    (可以打印PDF版本), manual pages(man 文檔), 純文本
  2. 完備的交叉引用:
    語(yǔ)義化的標(biāo)簽,并可以自動(dòng)化鏈接函數(shù),類,引文,術(shù)語(yǔ)及相似的片段信息
  3. 明晰的分層結(jié)構(gòu):
    可以輕松的定義文檔樹,并自動(dòng)化鏈接同級(jí)/父級(jí)/下級(jí)文章
  4. 美觀的自動(dòng)索引: 可自動(dòng)生成美觀的模塊索引
  5. 精確的語(yǔ)法高亮: 基于 Pygments 自動(dòng)生成語(yǔ)法高亮
  6. 開放的擴(kuò)展: 支持代碼塊的自動(dòng)測(cè)試,并包含Python模塊的自述文檔(API
    docs)等
  7. 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è)步驟:

  1. 將rst轉(zhuǎn)換為md(Markdown): pandoc xxx.rst -o xxx.md
  2. 解決md里面涉及到的交叉引用和代碼塊等格式問題键兜,我已經(jīng)寫了相應(yīng)的小程序:
    python post2md.py xxx.rst
  3. 使用一款非常有情懷非常強(qiáng)大還開源的markdown轉(zhuǎn)微信公眾號(hào)的工具markdownnice,直接將上面轉(zhuǎn)換好的md復(fù)制到這個(gè)工具中穗泵,點(diǎn)擊復(fù)制微信公眾號(hào)按鈕普气,然后直接粘貼到微信公眾號(hào)的圖文里面就得到相應(yīng)的效果(就像本文)。

動(dòng)畫鏈接
公眾號(hào)圖文示例

唯一需要注意的是佃延,為了使微信公眾號(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)畫所示。

動(dòng)畫鏈接

其他

除了常用的html和pdf格式,sphinx還可以生成電子書epub格式,還有man格式莱睁。
還有一些別的,可以自行研究了品擎。

最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
  • 序言:七十年代末,一起剝皮案震驚了整個(gè)濱河市备徐,隨后出現(xiàn)的幾起案子萄传,更是在濱河造成了極大的恐慌,老刑警劉巖,帶你破解...
    沈念sama閱讀 217,185評(píng)論 6 503
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件秀菱,死亡現(xiàn)場(chǎng)離奇詭異振诬,居然都是意外死亡,警方通過查閱死者的電腦和手機(jī)衍菱,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 92,652評(píng)論 3 393
  • 文/潘曉璐 我一進(jìn)店門赶么,熙熙樓的掌柜王于貴愁眉苦臉地迎上來,“玉大人脊串,你說我怎么就攤上這事辫呻。” “怎么了琼锋?”我有些...
    開封第一講書人閱讀 163,524評(píng)論 0 353
  • 文/不壞的土叔 我叫張陵放闺,是天一觀的道長(zhǎng)。 經(jīng)常有香客問我缕坎,道長(zhǎng)怖侦,這世上最難降的妖魔是什么? 我笑而不...
    開封第一講書人閱讀 58,339評(píng)論 1 293
  • 正文 為了忘掉前任谜叹,我火速辦了婚禮匾寝,結(jié)果婚禮上,老公的妹妹穿的比我還像新娘荷腊。我一直安慰自己艳悔,他們只是感情好,可當(dāng)我...
    茶點(diǎn)故事閱讀 67,387評(píng)論 6 391
  • 文/花漫 我一把揭開白布停局。 她就那樣靜靜地躺著很钓,像睡著了一般香府。 火紅的嫁衣襯著肌膚如雪董栽。 梳的紋絲不亂的頭發(fā)上,一...
    開封第一講書人閱讀 51,287評(píng)論 1 301
  • 那天企孩,我揣著相機(jī)與錄音锭碳,去河邊找鬼。 笑死勿璃,一個(gè)胖子當(dāng)著我的面吹牛擒抛,可吹牛的內(nèi)容都是我干的。 我是一名探鬼主播补疑,決...
    沈念sama閱讀 40,130評(píng)論 3 418
  • 文/蒼蘭香墨 我猛地睜開眼歧沪,長(zhǎng)吁一口氣:“原來是場(chǎng)噩夢(mèng)啊……” “哼!你這毒婦竟也來了莲组?” 一聲冷哼從身側(cè)響起诊胞,我...
    開封第一講書人閱讀 38,985評(píng)論 0 275
  • 序言:老撾萬(wàn)榮一對(duì)情侶失蹤,失蹤者是張志新(化名)和其女友劉穎锹杈,沒想到半個(gè)月后撵孤,有當(dāng)?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體迈着,經(jīng)...
    沈念sama閱讀 45,420評(píng)論 1 313
  • 正文 獨(dú)居荒郊野嶺守林人離奇死亡,尸身上長(zhǎng)有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點(diǎn)故事閱讀 37,617評(píng)論 3 334
  • 正文 我和宋清朗相戀三年邪码,在試婚紗的時(shí)候發(fā)現(xiàn)自己被綠了裕菠。 大學(xué)時(shí)的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片。...
    茶點(diǎn)故事閱讀 39,779評(píng)論 1 348
  • 序言:一個(gè)原本活蹦亂跳的男人離奇死亡闭专,死狀恐怖奴潘,靈堂內(nèi)的尸體忽然破棺而出,到底是詐尸還是另有隱情影钉,我是刑警寧澤萤彩,帶...
    沈念sama閱讀 35,477評(píng)論 5 345
  • 正文 年R本政府宣布,位于F島的核電站斧拍,受9級(jí)特大地震影響雀扶,放射性物質(zhì)發(fā)生泄漏。R本人自食惡果不足惜肆汹,卻給世界環(huán)境...
    茶點(diǎn)故事閱讀 41,088評(píng)論 3 328
  • 文/蒙蒙 一愚墓、第九天 我趴在偏房一處隱蔽的房頂上張望。 院中可真熱鬧昂勉,春花似錦浪册、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 31,716評(píng)論 0 22
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽(yáng)。三九已至攒至,卻和暖如春厚者,著一層夾襖步出監(jiān)牢的瞬間,已是汗流浹背迫吐。 一陣腳步聲響...
    開封第一講書人閱讀 32,857評(píng)論 1 269
  • 我被黑心中介騙來泰國(guó)打工库菲, 沒想到剛下飛機(jī)就差點(diǎn)兒被人妖公主榨干…… 1. 我叫王不留,地道東北人志膀。 一個(gè)月前我還...
    沈念sama閱讀 47,876評(píng)論 2 370
  • 正文 我出身青樓熙宇,卻偏偏與公主長(zhǎng)得像,于是被迫代替她去往敵國(guó)和親溉浙。 傳聞我的和親對(duì)象是個(gè)殘疾皇子烫止,可洞房花燭夜當(dāng)晚...
    茶點(diǎn)故事閱讀 44,700評(píng)論 2 354