Sphinx Book Theme 使用教程

Sphinx Book Theme 使用教程

sphinx-book-themeA clean book theme for scientific explanations and documentation with Sphinx项目地址:https://gitcode.com/gh_mirrors/sp/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 的外观和行为。

sphinx-book-themeA clean book theme for scientific explanations and documentation with Sphinx项目地址:https://gitcode.com/gh_mirrors/sp/sphinx-book-theme