# 使用Sphinx管理个人学习笔记 ## 0. 前言这个网站是用Markdown写的。我学习了以后发现Markdown真的非常适合记笔记，不需要考虑格式问题，最重要的是语法非常简单，比Latex简单多了。虽然说最后呈现出来的效果就是个简单的html，但是省去了手撸html标签的步骤。 --- ## 1. Markdown语法语法可以参考这个知乎上的[这篇](https://zhuanlan.zhihu.com/p/496076040)文章，其效果见网站上的另一篇文档[*这是用来学习markdown语法的一级标题*](markdown_tutorial.html)。VSCode的Markdown插件也很好用，可以实现实时预览。 --- ## 2. Sphinx环境配置 Markdown写完后需要转换成html才能被浏览器以网页的形式打开。转换成html的方案很多，可以在服务端用javascript转换，也可以转换成静态html网页。我一度也考虑过使用jekyll，但试用感觉仍然过于庞大，还需要安装一堆Ruby的依赖。后来我在看Jupyter和Python的相关文档时发现它们是用Sphinx生成的，十分简洁，整个网站架构就是一个文档库，非常适合这种应用场景。 ### 安装安装Sphinx有关的包： ``` bash pip install sphinx pip install sphinx-autobuild pip install sphinx_rtd_theme pip install recommonmark pip install sphinx_markdown_tables ``` ### 编辑项目创建并建立目录，执行命令 ``` bash sphinx-quickstart ``` 根据提示选择要不要把源代码和编译产物分开，选择y。然后设置项目名、作者名、版本号，这些后续是可以修改的。之后目录下会生成一个Makefile，一个source目录，一个build目录。所有的Markdown源文件就可以recursively保存在source目录里。例如，当前这一级目录下的index.rst用来设置这一级的标题，和这一级有那几篇内容，再下一级又有一个index.rst用来配置下一级的内容。 conf.py是用来配置插件和主题的。*sphinx_rtd_theme*是Read the Docs官方出品的一系列主题，在[这里](https://sphinx-themes.readthedocs.io/en/latest/)可以预览，在conf.py可以设置成其他喜欢的主题。 ``` python extensions = ['recommonmark', 'sphinx_markdown_tables'] html_theme = 'sphinx_rtd_theme' ``` ### 热部署预览在本地调试时可以使用sphinx-autobuild热部署进行预览。其中host默认是localhost，port默认是8000，然后在本地浏览器中就可以打开，每次更新源代码和设置都可以实时看到效果。 ``` bash sphinx_autobuild source build/html --host= --port= ``` ### 编译试用后发现sphinx-autobuild存在一些bug，比如中间级别的目录标题会被显示成*Untitled*。为了稳定性，最终部署到服务器上的应该是个静态网页，所以需要编译。 ``` bash sphinx-build source build ``` 所有source里的源代码都被编译成了build里的网页。 --- ## 3. nginx展示静态网页在nginx的配置文件`/etc/nginx/sites-enabled/default`里添加一条匹配规则: ``` nginx location /notes { index index.html; } ``` 重新加载配置后nginx就会在 `nginx根目录/notes/` 下面寻找index.html。 nginx根目录的路径则默认是在`/var/www/html/`，我原本想放在自己的home里，但是nginx没有我的文件系统的权限，会报403 Forbidden Error，所以要把编译好的网页复制到`/var/www/html/notes/`下面。 --- ## 参考资料 Markdown Markdown生成html Sphinx nginx