Sphinx和rst在科研笔记和学术博客中的高效用法

2022-03-21 00:00:00 文档 文件 生成 插件 格式

我们从小开始接触计算机的方式就让我们陷入了一种怪圈儿，比如操作系统只会用Windows、码字只知道word而且相信大多数人到现在依然还用不好、处理简单的文本表格只知道用excel。这些工具当然很好，也很强大，而且使用门槛低，也是广大人民日常工作中的必备工具。 但是，适用于大多数人就一定说明了它缺少了很多特性。尤其是对于科研工作者，这些基础的工具很难满足一些特定的需求。今天我就来介绍一种码字方式：码一份字，发布为多种平台(或格式)，而且很美观！这个神器就是Sphinx+rst！

什么是RST？

reStructuredText 是扩展名为 .rst 的纯文本文件，含义为"重新构建的文本"，也被简称为：RST 或 reST； 是 Python 编程语言的 Docutils 项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。 该项目类似于 Java 的 JavaDoc 或 Perl 的 POD 项目。 Docutils 能够从 Python 程序中提取注释和信息，格式化成程序文档。 .rst 文件类似于.md(Markdown)文件，是轻量级标记语言的一种， 被设计为容易阅读和编写的纯文本，并且可以借助 Docutils 这样的程序进行文档处理， 可以方便地转换为 HTML , Latex, Markdown 等多种格式。

rst在标记功能上比md丰富太多了，而且在Sphinx的框架下可以非常方便地使用各种插件，来实现各种不同特定需求。 比如地学领域常用的绘图和数据处理软件gmt，其开发团队现在已经开发了适用于Sphinx的插件sphinx_gmt， 这个插件的功能就是可以直接在rst文件中进行绘图，类似于Sphinx内置的python绘图插件.. plot::。 比如在rst文件中写入如下所示的文字，就可以直接自动根据你的gmt绘图命令将图片绘制好并嵌入到终生成的html文件，或者pdf中， 而不需要先找个地方运行gmt命令画图，然后在把图片插入到wrod中再导出为pdf。用rst码字，根本没有这么多麻烦事儿，全都是自动化！

.. gmtplot::
 :language: bash
 :show-code: false

 gmt pscoast -Rg -JW12c -Ba60 -Gblack > globe.ps
复制代码

这篇文章就是用rst写的，所以上面说的gmt插件的例子是实例！

像上面提到的这种插件还是非常非常多的，如果懂一点python编程，还可以根据自己的需要写一个插件。 (其实这个gmt的插件，两年前我已经写出来了而且在用了，类似的我还写了tikz的插件，只是自己用没有公开发布) 基于rst的基本功能还有这些插件的帮助，学术写作过程中常用的公式编写、图-表-公式-列表等交叉引用、参考文献引用、代码块等需求，都是完美解决的！

什么是Sphinx？

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是由Sphinx生成的， 并且它已成为Python项目的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持。 除了写程序项目的文档之外，还可以用Sphinx写博客，其实用它来写博士论文都不在话下。 本文当然也是使用 Sphinx生成的，它采用reStructuredText! （博客首页为: www.scibyte.cn/blog/zh/blo…) 所以，Sphinx和rst有着不可分割的关系。 可以这么理解：Sphinx是一个Python写的程序，可以使用Python写配置及插件，将rst标记的文档生成各种优美的格式。 其特性如下：

  1. 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本
  2. 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
  3. 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
  4. 美观的自动索引: 可自动生成美观的模块索引
  5. 的语法高亮: 基于 Pygments 自动生成语法高亮
  6. 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等
  7. Sphinx 使用 reStructuredText 作为标记语言, 可以享有Docutils为reStructuredText提供的分析，转换等多种工具.

如何实现多平台部署

上面已经讲了Sphinx和rst的特性，可以将同一份rst文档，生成各种不同的格式以供不同的平台发布。 下面我将重点介绍一下rst->网页博客->公众号图文的效果。

网页平台

Sphinx大的特性就是自定义格式，比如生成的网页html文件，可以自定义html的模板和样式(css)。 比如我的博客，就是自己用Sphinx写的。 每次写完一篇博文的rst文件然后只需要运行一个几行简单的命令，就可以完成生成html到网络服务器的部署，那是相当的省事儿！ 比如一个操作示例用下面的动画表示：

微信公众号

自己的博客自己做主，各种样式都可以自己定义，这也是轻松的。 但是如果想将同一篇博文也发布到微信公众号里面，一般情况下还是非常费劲的，谁排版过微信谁知道其中的酸爽！ 其实如果我们用rst写完一篇博文，根本不需要用什么秀米啥的排版搞半天，基本上可以用代码分分钟搞定微信公众号上的排版。 基本上以下几个步骤：

  1. 将rst转换为md(Markdown): pandoc xxx.rst -o xxx.md
  2. 解决md里面涉及到的交叉引用和代码块等格式问题，我已经写了相应的小程序: python post2md.py xxx.rst
  3. 使用一款非常有情怀非常强大还开源的markdown转微信公众号的工具markdownnice，直接将上面转换好的md复制到这个工具中，点击复制微信公众号按钮，然后直接粘贴到微信公众号的图文里面就得到相应的效果（就像本文）。

需要注意的是，为了使微信公众号发文在一分钟内搞定，那rst文件中的图片必须使用自定义的图床来解决，否则图片可能会无法上传到公众号里面。 这个是无法改变的，它就是那样！

Latex或PDF

在大多数情况下我们都有生成pdf文件的需求，比如开发了一款学术软件，在投稿的时候，期刊要求提供说明文档或者操作手册。 这东西用Sphinx编写简直再好不过了，是需要用简单的一个命令 make latex 就可以生成文档的latex所有文件， 然后到latex文件的目录运行一个命令 make 就可以生成pdf文件。 几乎是分分钟的事儿，操作过程如下面的动画所示。

其他

除了常用的html和pdf格式，sphinx还可以生成电子书epub格式，还有man格式。 还有一些别的，可以自行研究了。

相关文章