基于Sphinx和furo的个人笔记文档网站搭建教程

Sphinx + Github个人笔记

准备条件

1. github账号

   使用github进行文档版本管理

2. 安装Python

   有很多博客可以参考，自行百度

Sphinx创建文档

Sphinx是一个基于Python的文档生成项目，开始是用来生成 Python 官方文档的工具，更多介绍可参考官网：https://www.sphinx.org.cn/ 。

1. 安装Sphinx

Github地址为：https://github.com/sphinx-doc/sphinx

当然也可以在命令窗口进行pip安装：

pip install -U sphinx

2. 创建文档

github上新建一个仓库，这个仓库就是托管自己文档的仓库，没有的话就新建一个；然后将其克隆到本地，在项目根目录下创建一个docs目录，cd进入到该目录，执行命令：

Albert@DESKTOP-P96RPMS MINGW64 /g/Note/docs
$ sphinx-quickstart
Welcome to the Sphinx 4.5.0 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: Notes
> Author name(s): albert
> Project release []: 0.1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN

Creating file G:\Note\docs\source\conf.py.
Creating file G:\Note\docs\source\index.rst.
Creating file G:\Note\docs\Makefile.
Creating file G:\Note\docs\make.bat.

Finished: An initial directory structure has been created.

上面配置可以按照默认的，有些参数也可以自己修改，稍后对生成的conf.py配置文件进行修改。

此时的文档的目录结构为：

│   make.bat
│   Makefile
│
├───build
└───source
    │   conf.py
    │   index.rst
    │
    ├───_static
    └───_templates

• build 存放编译后的文件
• source/_static 存放静态文件
• source/_templates 存放模板文件
• source/conf.py 项目配置文件，上面的配置可以在这里面修改
• source/index.rst 首页

3. 编译

   对index.rst文件进行编译生成HTML以及相关静态文件：

   Running Sphinx v4.5.0
   loading translations [zh_CN]... done
   making output directory... done
   building [mo]: targets for 0 po files that are out of date
   building [html]: targets for 1 source files that are out of date
   updating environment: [new config] 1 added, 0 changed, 0 removed
   reading sources... [100%] index
   looking for now-outdated files... none found
   pickling environment... done
   checking consistency... done
   preparing documents... done
   writing output... [100%] index
   generating indices... genindex done
   writing additional pages... search done
   copying static files... done
   copying extra files... done
   dumping search index in Chinese (code: zh)... done
   dumping object inventory... done
   build succeeded.
   
   The HTML pages are in build\html.
   

这样在build文件夹里得到index.html文件。

修改主题

我这里使用的是furo，需要下载该主题并修改：

pip install furo

在conf.py中修改配置html_theme: theme，然后make html就会出现新的页面。

当然还有一些配置可自行修改。

配置Markdown

Sphinx默认使用 reStructuredText 标记语言，由于已经习惯使用markdown进行文档编辑，下面来配置markdown：

1. 安装recommonmark插件

   pip install recommonmark
   

2. 安装支持markdown表格的插件

   pip install sphinx_markdown_tables
   

3. 配置source/conf.py文件

   extensions = ['recommonmark', 'sphinx_markdown_tables']
   

   在source目录下创建一个markdown文件，将markdown文件名添加到source/index.rst 中，

   .. toctree::
      :maxdepth: 2
      :caption: Contents:
      
       windows-shortcuts.md
   

   make html即可。

4. Git仓库和本地工程连接

   本地工程即本地仓库，现在本地打开git bash，找到该项目的根目录，然后执行以下命令：

   git init
   git add .
   git commit -m 'first commit'
   git remote add origin git@github.com:你的github仓库地址
   git push -u origin main 
   # 第一次上传时可以加上-u参数，以后再提交时就不用了，只需要git push
   

   以上操作之后即可将本地库上传到远程仓库中。

   但在这里虽然上传到github了，但是首页并没有index.html，在使用githubpages时并不会有任何反应的，所以需要将生成的页面文件夹复制一份。

5. 使用Github Pages

   本地仓库：根目录下新建文件夹docs；

   重新将本地仓提交到远程仓，然后在设置里选择githubpages的路径docs，而不是默认的root。

点击save即可。

6. 操作命令

   # 生成页面
   make html
   # 复制渲染好的画面
   cp -r build/html/* docs/
   # 远程提交
   git add .
   git commit -m "add logo"
   git push
   

遇到的问题

1. 显示页面但没有css格式渲染

   默认情况下，Github7 Pages托管在JekyII上。但是，JekyII不支持Sphinx，因此它无法读取诸如_static之类的路径。作为响应，需要创建一个空白.nojekyll文件。

   make html重新构建，推送到远程仓库。

   注：如果开了代理（梯子）需要关了进行测试，然后再打开。

2. 出现在不慎多次提交后出现 (master|REBASE 1/2)

   回退提交

   git rebase --abort
   

3. 底部icons

   fontawesome

参考博客：

.jekyll问题

使用单个仓库配置 GitHub Pages + Sphinx

Sphinx简明教程

[视频1]使用Sphinx搭建本地(window)文档并把它部署到网上(github)成为blog

[视频2]使用Sphinx搭建本地(window)文档并把它部署到网上(github)成为blog

使用SSH建立Git 远程仓库和本地库连接

furo官方教程