win11使用sphinx编写文档并部署到github page

Reference

1 安装

安装python3，这个自己找教程安装即可，记得配置环境变量
打开cmd，输入
bash 复制代码
```
pip install sphinx
```
创建一个文件夹zpdocs，在文件夹内打开cmd，初始化一个sphinx
bash 复制代码
```
sphinx-quickstart
```
bash 复制代码
```
> Separate source and build directories (y/n) [n]: y
> Project name: zpdocs
> Author name(s): zp
> Project release []: 0.1
> Project language [en]: zh_CN
```
执行完毕后，就可以看见创建的工程文件:
bash 复制代码
```
|- build 
|- source
	|- _static 
	|- _templates 
	|- conf.py 
	|- index.rst
|- Makefile 
|- make.bat 
```
- build：文件夹，当你执行make html的时候，生成的html静态文件都存放在这里
- source/_static：文件夹：图片,js等存放地址
- source/_templates：文件夹:模板文件存放
- source/index.rst：索引文件,文章目录大纲
- source/conf.py：配置文件
- make.bat：windows平台用于编译文档项目的makefile文件
- Makefile：非windows平台用于编译文档项目的makefile文件

2 build项目

在文件夹zpdocs内打开cmd，运行
bash 复制代码
```
./make html
```
打开zpdocs/build/html/index.html，编译成功
编译为http服务，这样可以通过ip地址查看网页
1. 安装sphinx-autobuild
  bash 复制代码
```
pip install sphinx-autobuild
```
2. 重新编译
  bash 复制代码
```
sphinx-autobuild source build/html
```

3 更改样式主题

到Sphnix官网查看自己想要样式
我使用Book主题，安装sphinx-book-theme
bash 复制代码
```
pip install sphinx-book-theme
```
修改source/conf.py文件中的html_theme字段
python 复制代码
```
html_theme = 'sphinx_book_theme'
```

在source/conf.py文件中的添加以下内容

bash 复制代码

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown'
}

html_title = "My amazing documentation"

html_theme_options = {
    "show_navbar_depth": 1,
    "max_navbar_depth": 2,
    "collapse_navbar": True,
    "home_page_in_toc": True,
    "use_download_button": False,
}

重新编译
bash 复制代码
```
sphinx-autobuild source build/html
```

4 支持markdown

Sphinx默认只支持reST格式的文件。

如果相要使用markdown格式的文档，还要安装markdown支持工具，命令如下：
bash 复制代码
```
pip install recommonmark
pip install sphinx_markdown_tables
```
修改source/conf.py的extensions字段
bash 复制代码
```
extensions = ['recommonmark','sphinx_markdown_tables']
```
重新编译
bash 复制代码
```
sphinx-autobuild source build/html
```

5 编辑网页内容

修改source文件夹目录结构如下

bash 复制代码

|- build 
|- source
	|- _static 
	|- _templates 
	|- chapter1
		|- section1
			|- README.md
		|- index.rst
	|- chapter2
		|- section1
			|- README.md
		|- index.rst
	|- conf.py 
	|- index.rst
|- Makefile 
|- make.bat

source/index.rst

bash 复制代码

WELCOME!
=============================
.. toctree::  
   :maxdepth: 2  
   :caption: Contents  

   Chapter1<chapter1/index>  
   Chapter2<chapter2/index>

source/chapter1/index.rst

bash 复制代码

Chapter 1
=============================

.. toctree::  
   :maxdepth: 2  
   :caption: Chapter 1  Contents

   S1.1<section1/README>

source/chapter2/index.rst

bash 复制代码

Chapter 2
=============================

.. toctree::  
   :maxdepth: 2  
   :caption: Chapter 2  Contents

   S2.1<section1/README>

source/chapter1/section1/README.md
bash 复制代码
```
# S1.1
```
source/chapter2/section1/README.md
bash 复制代码
```
# S2.1
```

6 部署到github page

在远程仓库创建一个仓库
在zpdocs文件夹打开cmd，输入./make clean清除build缓存
修改conf.py，添加
bash 复制代码
```
extensions = [...,'sphinx.ext.githubpages',...]
```
这个插件会为生成后的文档添加 .nojekyll 文件，也会为 GitHub Pages 自定义域名添加 CNAME 文件。如果没有 .nojekyll， GitHub Pages 会认为 _ 开头的文件夹是 jekyll 内部文件夹，然后将它过滤掉。

注意: Sphinx 文档的文件名不能使用大写字母。因为 Sphinx 在 windows 上输出时会把的文件名转成小写, 而

GitHub Pages 的路由是大小写敏感的。无法正确链接到使用了大写字母作为文件名的文件。
重新编译
bash 复制代码
```
sphinx-autobuild source build/html
```
将build/html的文件推送到仓库的main分支，仓库中setting->page设置如下：