Sphinx RTD 主题项目教程

Sphinx RTD 主题项目教程

sphinx_rtd_themeSphinx theme for readthedocs.org项目地址:https://gitcode.com/gh_mirrors/sp/sphinx_rtd_theme

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'

sphinx_rtd_themeSphinx theme for readthedocs.org项目地址:https://gitcode.com/gh_mirrors/sp/sphinx_rtd_theme