sphinx等工具更适合于有多个章节、比较大的文档的编写,而markdown则比较适合于单篇、比较短的文章的编写,基本就是latex中的book和chapter的区别,sphinx比较适合写book,而markdown比较适合写chapter。markdown近来比较多地被应用于博客的编写中。
那么如果我们对某领域进行了系统学习,并用sphinx进行了的学习记录,如何发表成博客呢?我们可以按章节把sphinx文档进行拆分,每个章节发一篇博客,最终组成一个系列的博客。达成这一目标,最简单的方式是,把每个章节的rst格式的文件转成markdown语法的文件,并发表在支持markdown语法的博客上(wordpress也有markdown的插件)。
目前,网上似乎没有合适的工具可以把rst转为markdown。不过,我们可以自己动手,使用python和正则表达式来进行转换,python正则的使用,见本人博客 [ python入门系列(3) – python语言基础语法 ]。
这里,我们只对一些比较常用的sphinx语法进行处理,sphinx的使用,见本人的另一篇博客 [ Sphinx-doc编写文档 ]
下面针对比较常用的几个标记进行分别讨论:
- 行内标记
- 列表
- 标题
- 标注
- 代码段
- 代码包含
- 图片
- 链接
其中行内标记、列表在sphinx和markdown的语法一样,不做处理。图片标记因为主要用于博客,图片要手动单独上传,所以图片的也不处理。代码包含因为博客上无法上传源码文件,所以也不处理。链接处理比较麻烦,所以也不处理。所以我们仅处理以下内容:
- 标题
- *标注
- 代码段
标题
对于标题,我们只处理一级标题,二级标题,三级标题。在sphinx中,三种标题形如:
一级标题
======
二级标题
------
三级标题3
++++++
我们要把它转换为sphinx中的标题:
# **一级标题**
## **二级标题**
### **三级标题**
为了效果,我们把每级标题的字体都用**
加粗。同时,每个二级标题前面都加一条分割线。
一级标题
sphinx的一级标题的正则如下:
t0Pattern = re.compile(u'''(^.*?)\n=+''', re.MULTILINE)
正则中的sub置换方法为:
def t0Repl(matched):
rs = matched.groups()[0]
rs = "# **%s**" % rs.strip()
return rs
调用方法:
tt = re.sub(t0Pattern, t0Repl, tt)
其中tt为文件内容
二级标题
sphinx的二级标题的正则如下:
t1Pattern = re.compile(u'''(^.*?)\n-+''', re.MULTILINE)
正则中的sub置换方法为:
def t1Repl(matched):
rs = matched.groups()[0]
rs = "\n---\n## **%s**" % rs.strip()
return rs
调用方法: