使用Sphinx将个人笔记变成文档的形状~

本文从记录笔记和后期归档出发,对比了多个平台记录笔记的特点和优势,最后详细记录了使用Sphinx编译笔记为html的例子。

需求分析&平台对比

首先关于为什么选用Sphinx编译笔记和文档,Hexo和gitbook也挺香的。Sphinx是综合对比下的选择。

首先是Typora,它简直就是写md的神器,写md的同时还能预览,没有大部分md编辑器左边写md右边预览的那种割裂感。但只适合单个文档的编辑,如果加上多标签那就完美了。有时大概有印象要找的内容在某篇笔记中,但没法全局搜索就有些麻烦。

然后有朋友推荐了gitnote,虽然它可以多标签页编辑多个md了,但问题同样是显著的——慢且默认为md编辑模式,预览还得多切换一次。慢是说它每次启动都得卡半天(已经安装在固态盘中),且经常会有高CPU和磁盘占用,可能会定时扫描文件变动实现版本管理。

也参考了朋友的意见使用Trello记录笔记,但感觉它更多是针对工作流的,对于个人笔记而言好像又太复杂了。

image-20210116085358179

至此我的需求大致明确,平常记录笔记使用md;后期方便查阅和搜索;查阅和搜索时秒开;最好有多标签,没有也可以;最后,编译出来的颜值要够。因而将目标转向了将md文件编译为html的一些框架,编辑和整理时通过Typora书写,查阅时可以通过网页的形式全局搜索。

gitbook和Hexo等框架可以很方便的将md文件编译为html,但gitbook编译出的html需要挂在Nginx上,不然没法跳转;hexo虽然没有上述缺点,但它是针对blog的框架,不太适合笔记。因而最终选定了Sphinx,静态网页且够快够好看。

使用Nginx挂载gitbook编译的链接可以参考我以前的推文:《开发文档加载不再卡顿,亿点点提升》

使用Sphinx记笔记

环境搭建

首先安装必要的包,我用的python环境是Anaconda,日常不激活conda环境而是直接用。安装包用匹配即可,用conda管理环境反而麻烦(在不需要做环境隔离的情况下)。

1
2
pip install sphinx sphinx_rtd_theme sphinx-autobuild 
pip3 install recommonmark sphinx_markdown_tables

首先安装本体和一个主题,还有一个自动编译的工具。第二行安装了两个插件,添加了对md文件的支持。

框架搭建

在一个空目录下运行sphinx-quickstart,输出的信息大致如下,除了最后的语言注意填写zh_CN,其他的几个随便填,后面可以改。

image-20210114222655913

生成文件后有一些奇奇怪怪的文件,需要关注的有两个

  • conf.py: Sphinx 的配置,设置插件主题等
  • index.rst:文档项目起始文件。

打开conf.py,修改主题,添加插件,找到相关的内容改成这样。还可以添加其他的插件实现其他的效果和功能,sphinx_rtd_theme主题比较好看,有其他颜值高的主题求推荐一波。

1
2
3
4
5
6
extensions = [
'recommonmark',
'sphinx_markdown_tables'
]

html_theme = 'sphinx_rtd_theme'

至此,可以在有make.bat或者Makefile的目录下运行make html编译文档,编译出来的文件在build\html目录下。

可以使用sphinx-autobuild命令自动编译,可以实时刷新写好的文档,但是文档有错误时不会显示报错信息。会在localhost的某个端口挂载编译好的静态html,并实时刷新。

1
sphinx-autobuild source build/html

编写自己的文档和笔记

sphinx用的是一套叫reStructuredText的纯文本标记语法,功能比md更丰富,语法参考链接

不过写文档可以不用太了解rst的语法,打开index.rst,结构大致如下

toctree的三个空格很重要,了少了都报错,最下面的是参考链接,可以不要。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
这是标题
=============================

可以写点什么东西

.. toctree::
:maxdepth: 2
:caption: 目录标题:

about
test/testfile



这也是标题
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

index.rst的toctree下面加入自己写的内容后要建立对应的文件

1
2
3
mkdir test
touch about.md
touch test\testfile.md

由于之前安装的recommonmark插件,可以愉快的使用md写文档了。

可以把下面的内容粘贴到新建的md中,方便编译测试

1
2
3
4
5
6
7
8
9
10
11
12
13
# 标题1

## 标题2

### 标题3

#### 标题4

##### 标题5

##### 标题6

正文正文

最终完成的效果,奇怪的笔记文档增加了。

image-20210114225944865

使用Sphinx编译自己的笔记文档还挺简单的,但是没搞明白之前还是挺蛋疼的,参考了一些链接但感觉还是写的不是太清楚,故我自己总结一下。

问题和改进

中文路径

目前出现了文档中存在中文路径时无法正常读取图片的bug,猜测是转义出了问题,不过没有修复完成。

image-20210114204629844

风格主题

现在使用的主题还有一点不太满意,代码高亮风格和其他的一些细节想改改,后续可能会研究研究怎么修改。

一文多发

众所周知md是最好的纯文本标记语言(狗头),csdn、知乎、公众号或者其他平台都支持md格式的文档。唯一的问题就是在本地环境下图片是相对路径,辗转到各个平台还得重新上传图片。一个解决办法是使用图床,将文档内的图片替换为外链后就可以多个平台复制粘贴发送一气呵成。

参考链接

文章目录
  1. 1. 需求分析&平台对比
  2. 2. 使用Sphinx记笔记
    1. 2.1. 环境搭建
    2. 2.2. 框架搭建
    3. 2.3. 编写自己的文档和笔记
  3. 3. 问题和改进
    1. 3.1. 中文路径
    2. 3.2. 风格主题
    3. 3.3. 一文多发
  4. 4. 参考链接
|