目录
一、sphinx安装与构建
1. 安装sphinx
python安装sphinx
pip install sphinx
2. 新建项目
安装完毕后转到任意目录测试,例如这里在D:\Temp\blog
目录,输入sphinx-quickstart
,则会自动生成一些文件
D:\Temp\blog>sphinx-quickstart
接下来是一些新建项目的选项
Separate source and build directories (y/n) [n]:
- 分离source
和build
目录,这里为方便管理源文件(markdown)和结果文件(html),选择y
Project name
- 项目名称,例如 MyBlogAuthor name(s)
- 作者, 例如 佚名Project release []
- 项目版本, 例如 1.0.0Project language [en]:
项目的语言,默认是英文, 例如 zh_CN, 这里可以查看文档的语言缩写
这样就配置好了一个新的项目MyBlog
, 我们可以在D:\Temp\blog
目录发现文件结构如图所示
D:\TEMP\BLOG\SOURCE
│—build
│—source
├─make.bat
└─Makefile
- build文件夹: 运行
make html
命令后,生成的文件会在这个目录中 - source目录:放置文档的源文件
- make.bat:可以在该目录下使用
make
命令,sphinx会自动解析 - makefile
3. 构建项目
构建项目,这里使用make html
命令,即’编译’source目录下的文件,在build目录生成html文件
D:\Temp\blog>make html
这样就在 \build\html\
目录生成相应的html文件,启动index.html
查看效果
但是html文件效果很不美观,接下来我们需要进行美化工作
二、页面美化
1. 安装配置主题
参考 Sphinx Themes Gallery,这里有很多可以选择的页面主题,点开后可以查看具体的用法,用法如下
- 下载主题
- 在项目的
\source\conf.py
中修改主题
这里以经典的Read the doc
主题为例,首先下载该主题
pip install sphinx-rtd-theme
在conf.py
中修改主题
...
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# 默认主题