Sphinx Book Theme 使用教程
1. 项目的目录结构及介绍
Sphinx Book Theme 的目录结构如下:
sphinx-book-theme/
├── docs/
│ ├── _static/
│ ├── _templates/
│ ├── conf.py
│ ├── index.rst
│ └── Makefile
├── sphinx_book_theme/
│ ├── static/
│ ├── templates/
│ ├── __init__.py
│ ├── theme.conf
│ └── util.py
├── .gitignore
├── LICENSE
├── MANIFEST.in
├── README.md
├── setup.cfg
└── setup.py
目录结构介绍
docs/
: 包含项目的文档文件,如配置文件、静态资源和模板。_static/
: 存放静态文件,如图片、CSS 和 JavaScript 文件。_templates/
: 存放自定义模板文件。conf.py
: Sphinx 配置文件。index.rst
: 文档的入口文件。Makefile
: 用于构建文档的 Makefile。
sphinx_book_theme/
: 主题的核心代码。static/
: 主题的静态资源文件。templates/
: 主题的模板文件。__init__.py
: 模块初始化文件。theme.conf
: 主题配置文件。util.py
: 工具函数文件。
.gitignore
: Git 忽略文件列表。LICENSE
: 项目许可证。MANIFEST.in
: 打包清单文件。README.md
: 项目说明文件。setup.cfg
: 安装配置文件。setup.py
: 安装脚本。
2. 项目的启动文件介绍
Sphinx Book Theme 的启动文件是 docs/conf.py
。这个文件包含了 Sphinx 文档项目的配置信息,如主题设置、扩展插件、路径配置等。
conf.py
主要配置项
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
project = 'Sphinx Book Theme'
copyright = '2021, Executable Books'
author = 'Executable Books'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
]
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_book_theme'
html_theme_options = {
'path_to_docs': 'docs',
'repository_url': 'https://github.com/executablebooks/sphinx-book-theme',
'use_repository_button': True,
}
html_static_path = ['_static']
3. 项目的配置文件介绍
Sphinx Book Theme 的配置文件主要包括 conf.py
和 theme.conf
。
conf.py
如上所述,conf.py
是 Sphinx 文档项目的配置文件,包含了项目的基本信息、扩展插件、主题设置等。
theme.conf
theme.conf
是主题的配置文件,定义了主题的样式和行为。
[theme]
inherit = basic
stylesheet = sphinx_book_theme.css
pygments_style = tango
主要配置项
inherit
: 继承的基本主题。stylesheet
: 主题的 CSS 文件。pygments_style
: 代码高亮样式。
通过这些配置文件,可以自定义和调整 Sphinx Book Theme 的外观和行为。