Sphinx RTD 主题项目教程
1. 项目的目录结构及介绍
Sphinx RTD 主题项目的目录结构如下:
sphinx_rtd_theme/
├── .github/
│ └── workflows/
├── docs/
│ ├── _static/
│ ├── _templates/
│ ├── conf.py
│ ├── index.rst
│ └── ...
├── sphinx_rtd_theme/
│ ├── static/
│ │ ├── css/
│ │ ├── js/
│ │ └── fonts/
│ ├── theme.conf
│ └── ...
├── .gitignore
├── .readthedocs.yml
├── LICENSE
├── MANIFEST.in
├── README.rst
├── setup.cfg
├── setup.py
└── tox.ini
目录结构介绍
.github/
: GitHub 配置文件,包含 CI/CD 工作流。docs/
: 项目文档目录,包含 Sphinx 文档配置和源文件。sphinx_rtd_theme/
: 主题的核心目录,包含静态资源和主题配置文件。.gitignore
: Git 忽略文件列表。.readthedocs.yml
: Read the Docs 配置文件。LICENSE
: 项目许可证。MANIFEST.in
: 打包清单文件。README.rst
: 项目介绍文档。setup.cfg
: 安装配置文件。setup.py
: 安装脚本。tox.ini
: 自动化测试配置文件。
2. 项目的启动文件介绍
Sphinx RTD 主题项目的启动文件主要是 setup.py
,它负责项目的安装和分发。以下是 setup.py
的主要内容:
from setuptools import setup, find_packages
setup(
name='sphinx_rtd_theme',
version='1.0.0',
url='https://github.com/readthedocs/sphinx_rtd_theme',
license='MIT',
author='Dave Snider',
author_email='dave.snider@gmail.com',
description='Read the Docs theme for Sphinx',
long_description=open('README.rst').read(),
packages=find_packages(),
include_package_data=True,
install_requires=[
'sphinx',
],
classifiers=[
'Development Status :: 5 - Production/Stable',
'Intended Audience :: Developers',
'License :: OSI Approved :: MIT License',
'Operating System :: OS Independent',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
'Programming Language :: Python :: 3.9',
],
)
启动文件介绍
name
: 项目名称。version
: 项目版本。url
: 项目仓库地址。license
: 项目许可证。author
: 项目作者。author_email
: 作者邮箱。description
: 项目简短描述。long_description
: 项目详细描述。packages
: 需要包含的包。include_package_data
: 是否包含包数据。install_requires
: 项目依赖。classifiers
: 项目分类信息。
3. 项目的配置文件介绍
Sphinx RTD 主题项目的配置文件主要包括 conf.py
和 .readthedocs.yml
。
conf.py
conf.py
是 Sphinx 文档的配置文件,位于 docs/
目录下。以下是 conf.py
的主要内容:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
import sphinx_rtd_theme
project = 'Sphinx RTD Theme'
copyright = '2021, Dave Snider'
author = 'Dave Snider'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
'sphinx_rtd_theme',
]
html_theme = 'sphinx_rtd_theme'