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

简介: 我们从小开始接触计算机的方式就让我们陷入了一种怪圈儿,比如操作系统只会用Windows、码字只知道word而且相信大多数人到现在依然还用不好、处理简单的文本表格只知道用excel。这些工具当然很好,也很强大,而且使用门槛低,也是广大人民日常工作中的必备工具。

什么是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! (博客首页为:
https://www.scibyte.cn/blog/zh/blog.html)
所以,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格式。
还有一些别的,可以自行研究了。

相关文章
|
2月前
|
前端开发 搜索推荐 JavaScript
"揭秘!Python高手如何用Sphinx玩转个人博客?从零搭建,美到犯规,技术干货一网打尽,让你的博客秒变网红级存在!"
【8月更文挑战第14天】Sphinx是Python社区中用于编写和技术分享的强大工具,以其易用性和美观的文档输出著称。本文介绍如何用Sphinx打造个性化博客。首先需安装Python、Sphinx及sphinx_rtd_theme主题。接着通过`sphinx-quickstart`命令初始化项目并配置基本选项。在`conf.py`中可自定义博客元信息和主题设置。
40 3
|
3月前
|
人工智能 数据挖掘 大数据
爆赞!GitHub首本标星120K的Python程序设计人工智能案例手册
为什么要学习Python? Python简单易学,且提供了丰富的第三方库,可以用较少的代码完成较多的工作,使开发者能够专注于如何解决问题而只花较少的时间去考虑如何编程。此外,Python还具有免费开源、跨平台、面向对象、胶水语言等优点,在系统编程、图形界面开发、科学计算、Web开发、数据分析、人工智能等方面有广泛应用。尤其是在数据分析和人工智能方面,Python已成为最受开发者欢迎的编程语言之一,不仅大量计算机专业人员选择使用Python进行快速开发,许多非计算机专业人员也纷纷选择Python语言来解决专业问题。 由于Python应用广泛,关于Python的参考书目前已经有很多,但将Pytho
|
4月前
技术笔记:tcolorbox宏包简明教程
技术笔记:tcolorbox宏包简明教程
127 0
|
5月前
|
Python
小白入门必备!计科教授的Python精要参考PDF开放下载!
随着互联网产业的高速发展,在网络上早已积累了极其丰富的Python学习资料,任何人都可以基于这些资源,自学掌握 Python。 但实际上,网络上充斥的资源太多、太杂且不成体系,在没有足够的编程/工程经验之前,仅靠“看”线上资源自学,的确是一件非常困难的事。
|
4月前
|
并行计算 开发者 Python
GitHub标星破千!这份Python并行编程手册,可以封神了!
现在这个时代是并行编程与多核的时代,硬件成本越来越低,如何充分利用硬件所提供的各种资源是每一个软件开发者需要深入思考的问题。若想充分利用所有的计算资源来构建高效的软件系统,并行编程技术是不可或缺的一项技能。
小白入门必备!计算机科学教程的Python精要参考PDF开放下载!
随着互联网产业的高速发展,在网络上早已积累了极其丰富的Python学习资料,任何人都可以基于这些资源,自学掌握 Python。 但实际上,网络上充斥的资源太多、太杂且不成体系,在没有足够的编程/工程经验之前,仅靠“看”线上资源自学,的确是一件非常困难的事。
|
SQL JavaScript 前端开发
DayDayUp:Markdown编辑器的简介、入门、使用方法(Markdown编辑器撰写博客)(一)
DayDayUp:Markdown编辑器的简介、入门、使用方法(Markdown编辑器撰写博客)
[雪峰磁针石博客]python GUI工具书籍下载-持续更新
python测试开发项目实战-目录 python工具书籍下载-持续更新 python 3.7极速入门教程 - 目录 Python GUI Programming Cookbook 2nd - 2017.

相关实验场景

更多