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! (博客首页为:
https://www.scibyte.cn/blog/zh/blog.html)
所以,Sphinx和rst有着不可分割的关系。
可以这么理解:Sphinx是一个Python写的程序,可以使用Python写配置及插件,将rst标记的文档生成各种优美的格式。
其特性如下:
-
丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX
(可以打印PDF版本), manual pages(man 文档), 纯文本
-
完备的交叉引用:
语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
-
明晰的分层结构:
可以轻松的定义文档树,并自动化链接同级/父级/下级文章
- 美观的自动索引: 可自动生成美观的模块索引
- 精确的语法高亮: 基于 Pygments 自动生成语法高亮
-
开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API
docs)等
-
Sphinx 使用 reStructuredText 作为标记语言,
可以享有Docutils为reStructuredText提供的分析,转换等多种工具.
如何实现多平台部署
上面已经讲了Sphinx和rst的特性,可以将同一份rst文档,生成各种不同的格式以供不同的平台发布。
下面我将重点介绍一下rst->网页博客->公众号图文的效果。
网页平台
Sphinx最大的特性就是自定义格式,比如生成的网页html文件,可以自定义html的模板和样式(css)。
比如我的博客,就是自己用Sphinx写的。
每次写完一篇博文的rst文件然后只需要运行一个几行简单的命令,就可以完成生成html到网络服务器的部署,那是相当的省事儿!
比如一个操作示例用下面的动画表示:
动画链接
网页博客示例
微信公众号
自己的博客自己做主,各种样式都可以自己定义,这也是最轻松的。
但是如果想将同一篇博文也发布到微信公众号里面,一般情况下还是非常费劲的,谁排版过微信谁知道其中的酸爽!
其实如果我们用rst写完一篇博文,根本不需要用什么秀米啥的排版搞半天,基本上可以用代码分分钟搞定微信公众号上的排版。
基本上以下几个步骤:
- 将rst转换为md(Markdown):
pandoc xxx.rst -o xxx.md
-
解决md里面涉及到的交叉引用和代码块等格式问题,我已经写了相应的小程序:
`python post2md.py xxx.rst`
- 使用一款非常有情怀非常强大还开源的markdown转微信公众号的工具markdownnice,直接将上面转换好的md复制到这个工具中,点击复制微信公众号按钮,然后直接粘贴到微信公众号的图文里面就得到相应的效果(就像本文)。
唯一需要注意的是,为了使微信公众号发文在一分钟内搞定,那rst文件中的图片必须使用自定义的图床来解决,否则图片可能会无法上传到公众号里面。
这个是无法改变的,它就是那样!
Latex或PDF
在大多数情况下我们都有生成pdf文件的需求,比如开发了一款学术软件,在投稿的时候,期刊要求提供说明文档或者操作手册。
这东西用Sphinx编写简直再好不过了,是需要用简单的一个命令make latex
就可以生成文档的latex所有文件,
然后到latex文件的目录运行一个命令 make
就可以生成pdf文件。 几乎是分分钟的事儿,操作过程如下面的动画所示。
其他
除了常用的html和pdf格式,sphinx还可以生成电子书epub格式,还有man格式。
还有一些别的,可以自行研究了。
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
物联网和智慧城市现状
云栖号资讯:【点击查看更多行业资讯】在这里您可以找到不同行业的第一手的上云资讯,还在等什么,快来! 智慧城市项目正在实现并进入主流意识。以下是有关使智慧城市成功的十个观察。 随着智慧城市走出炒作阶段,开始扩散并向前发展,其数量已达到临界点。 过去几年,全球宣布了数十个智慧城市项目。早期采用者已经在实施他们的智慧城市计划。 在智慧城市项目在全球范围内受到关注并且早期采用者已开始兑现其智慧城市愿景的时候,我们认为现在应该就智慧城市空间的运行状况进行一些高层次的观察。 以下是我们的十大观察结果: 1. 政策制定者对智慧城市计划越来越重视 这听起来似乎很明显,但并非总是如此。决策者现在已经更好地理解了智慧城市项目可以为城市带来的潜在好处,例如增加的经济机会,减少的交通拥堵,更少的污染和更高的宜居性。 尽管智慧城市计划的投资案例仍然具有挑战性,但这种加深的理解意味着决策者对将此类计划出售给居民和其他利益相关者更有信心。 2. 智慧城市投资案例不同 与部署物联网的其他行业相比,智慧城市的公共投资案例要复杂得多。 这源于预算限制公共支出,以及难以就支出优先事项达成政治共识。与智慧城市相关的许多好处也...
- 下一篇
java class文件详解
java class文件详解 目录 一、概述二、Class类文件的结构2.1、魔数和java版本号2.2、常量池2.3、访问标志 回到顶部一、概述各种不同平台的Java虚拟机, 以及所有平台都统一支持的程序存储格式——字节码(Byte Code)是构成平台无关性的基石,所以class文件主要用于解决平台无关性的中间文件。如下图所示: java虚拟机不与包括Java语言在内的任何程序语言绑定, 它只与“Class文件”这种特定的二进制文件格式所关联, Class文件中包含了Java虚拟机指令集、 符号表以及若干其他辅助信息。 每一个class文件都对应着唯一一个类或者接口的定义信息,但是相对地,类或者接口并不一定都必须定义在文件里(比如类或者接口也可以通过类加载器直接生成) 每个class文件都是由字节流组成,各个数据项目严格按照顺序紧凑地排列在文件之中, 中间没有添加任何分隔符,每个字节流含有8个二进制位,所有的16位,32位和64位长度的数据将通过2个,4个和8个连续的8位字节来对其进行表示,多字节数据总是按照big-endian(大端在前:也就是说高位字节存储在低的地址上面,而低位...
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
推荐阅读
最新文章
- Docker安装Oracle12C,快速搭建Oracle学习环境
- Jdk安装(Linux,MacOS,Windows),包含三大操作系统的最全安装
- SpringBoot2整合Redis,开启缓存,提高访问速度
- SpringBoot2全家桶,快速入门学习开发网站教程
- CentOS7编译安装Gcc9.2.0,解决mysql等软件编译问题
- 设置Eclipse缩进为4个空格,增强代码规范
- CentOS7,8上快速安装Gitea,搭建Git服务器
- CentOS7编译安装Cmake3.16.3,解决mysql等软件编译问题
- CentOS8编译安装MySQL8.0.19
- Docker快速安装Oracle11G,搭建oracle11g学习环境