打造个人笔记—01Sphinx快速上手

介绍

Sphinx 是一个基于 Python 的文档生成项目。最早只是用来生成 Python 的项目文档，使用 reStructuredText 格式(简称rst)。但随着 Sphinx 项目的逐渐完善，目前已发展成为一个大众可用的框架，很多非 Python 的项目也采用 Sphinx 作为文档写作工具，甚至完全可以用 Sphinx 来写书。非常适合打造个人笔记系统

安装

sphinx的安装需要python环境，先安装好python，直接用pip安装sphinx就行

pip install sphinx -y

编写文档

安装成功之后就可以开始写文档笔记了，找到一个空的文件夹，右键打开终端输入以下命令：

sphinx-quickstart

接着按提示输入相关信息就行：

这样就在这个空文件夹自动生成一些默认的文件了：

其中build是编译后生成的静态网页文件、pdf等等，source文件夹是写笔记的源文件，如markdown文件。

构件html

创建完项目，可以直接执行如下命令，看看生成的结果如何：

./make.bat html

查看结果

用浏览器打开build/html/index.html文件：

其它的内容的话，就需要继续往source里面新增笔记文件，然后编译生成就行了。

使用插件

sphinx默认使用的语法是rst，一般我们写笔记都是用markdown比较多，因此可以安装一个支持markdown的插件，让sphinx能识别markdown文件。

1.安装插件markdown插件

用pip安装如下两个包

pip install sphinx_markdown_tables recommonmark -y

2. 修改配置文件source/conf.py，修改其中的extensions、source_suffix变量，赋值如下：

extensions = [
	'recommonmark',
	'sphinx_markdown_tables',
]
source_suffix = {'.rst': 'restructuredtext','.md': 'markdown'}

如果没有extensions、source_suffix变量，直接声明赋值就行。

这个配置文件是一个py源代码。

修改完成之后，在source文件夹里面就可以直接新建md文件写笔记了。