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

zp1008611

已于 2024-08-13 11:34:35 修改

阅读量1k

点赞数 27

文章标签： sphinx github 全文检索

于 2024-08-11 21:05:27 首次发布

本文链接：https://blog.csdn.net/weixin_45699092/article/details/141106863

版权

Reference

https://blog.hszofficial.site/recommend/2020/11/27/%E4%BD%BF%E7%94%A8Sphinx%E5%86%99%E9%A1%B9%E7%9B%AE%E6%96%87%E6%A1%A3/
https://blog.csdn.net/hhy321/article/details/131150447?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522172336378516800175713307%2522%252C%2522scm%2522%253A%252220140713.130102334.pc%255Fall.%2522%257D&request_id=172336378516800175713307&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2_allfirst_rank_ecpm_v1~rank_v31_ecpm-1-131150447-null-null.142^v100pc_search_result_base1&utm_term=readthedocs%20sphinx%20github&spm=1018.2226.3001.4187
https://blog.csdn.net/gitblog_00003/article/details/136540329
https://how-to-use-sphinx-write.readthedocs.io/zh-cn/latest/
https://www.cnblogs.com/jonnyan/p/14207711.html

1 安装

安装python3，这个自己找教程安装即可，记得配置环境变量
打开cmd，输入
```
pip install sphinx
```
创建一个文件夹zpdocs，在文件夹内打开cmd，初始化一个sphinx
```
sphinx-quickstart
```
```
> 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
```
执行完毕后，就可以看见创建的工程文件:
```
|- 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，运行
```
./make html
```
打开zpdocs/build/html/index.html，编译成功
编译为http服务，这样可以通过ip地址查看网页
1. 安装sphinx-autobuild
```
pip install sphinx-autobuild
```
2. 重新编译
```
sphinx-autobuild source build/html
```

3 更改样式主题

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

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

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,
}

重新编译
```
sphinx-autobuild source build/html
```

4 支持markdown

Sphinx默认只支持reST格式的文件。
如果相要使用markdown格式的文档，还要安装markdown支持工具，命令如下：
```
pip install recommonmark
pip install sphinx_markdown_tables
```

修改source/conf.py的extensions字段

extensions = ['recommonmark','sphinx_markdown_tables']

重新编译
```
sphinx-autobuild source build/html
```

5 编辑网页内容

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

|- 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

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

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

source/chapter1/index.rst

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

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

   S1.1<section1/README>

source/chapter2/index.rst

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

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

   S2.1<section1/README>

source/chapter1/section1/README.md
```
# S1.1
```
source/chapter2/section1/README.md
```
# S2.1
```

6 部署到github page

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

注意: Sphinx 文档的文件名不能使用大写字母。因为 Sphinx 在 windows 上输出时会把的文件名转成小写, 而
GitHub Pages 的路由是大小写敏感的。无法正确链接到使用了大写字母作为文件名的文件。
重新编译
```
sphinx-autobuild source build/html
```
将build/html的文件推送到仓库的main分支，仓库中setting->page设置如下：