快速入门

快速入门#

欢迎使用 xyzstyle 主题！本指南将帮助您快速上手并充分利用这个现代、美观的 Sphinx 文档主题。

前提条件#

在开始之前，请确保您的环境中已安装以下内容：

  • Python 3.8 或更高版本

  • Sphinx 5.0 或更高版本

  • 对 Sphinx 生态系统 有基本了解

安装主题#

基本安装#

使用 pip 安装 xyzstyle 主题：

pip install xyzstyle

开发版本安装#

如果您想使用最新的开发版本，可以直接从 GitHub 安装：

pip install git+https://github.com/xinetzone/xyzstyle.git

激活主题#

在您的 Sphinx 配置文件 (conf.py) 中激活 xyzstyle 主题：

列表 1 conf.py#
# 设置使用 xyzstyle 主题
html_theme = 'xyzstyle'

# 主题标题
html_title = '我的 Sphinx 文档'

# 设置静态文件目录
html_static_path = ['_static']

# 设置 Logo 和图标
html_logo = '_static/images/logo.jpg'
html_favicon = '_static/images/favicon.jpg'

创建新项目#

如果您还没有 Sphinx 项目，可以按照以下步骤创建一个新的项目：

1. 创建项目目录#

mkdir my_sphinx_project
cd my_sphinx_project

2. 初始化 Sphinx 项目#

sphinx-quickstart docs

按照提示配置您的项目。完成后，您会在 docs 目录中看到 conf.py 和其他必要文件。

3. 应用 xyzstyle 主题#

编辑 docs/conf.py 文件，添加或修改以下配置：

列表 2 docs/conf.py#
# 使用 xyzstyle 主题
html_theme = 'xyzstyle'

# 添加必要的扩展
extensions = [
    'myst_nb',
    'sphinx_design',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx',
    'sphinx_copybutton',
]

4. 构建文档#

使用以下命令构建您的文档：

cd docs
sphinx-build -b html . _build/html

构建完成后，您可以在 _build/html 目录中查看生成的 HTML 文档。

基本配置选项#

xyzstyle 主题提供了丰富的配置选项，以下是一些常用的配置：

列表 3 基本主题配置#
html_theme_options = {
    # 启用侧边注释
    'use_sidenotes': True,

    # GitHub 仓库配置
    'repository_url': 'https://github.com/yourusername/yourproject',
    'repository_branch': 'main',
    'path_to_docs': 'docs',

    # 显示各种按钮
    'use_repository_button': True,
    'use_edit_page_button': True,
    'use_issues_button': True,
    'use_source_button': True,
    'back_to_top_button': True,

    # 公告横幅
    'announcement': '欢迎访问我的项目文档！🚀',

    # 启动按钮配置
    'launch_buttons': {
        'binderhub_url': 'https://mybinder.org',
        'colab_url': 'https://colab.research.google.com/',
        'notebook_interface': 'jupyterlab',
    },
}

高级特性#

API 文档自动生成#

xyzstyle 集成了 AutoAPI 扩展，可以自动生成 Python 代码的 API 文档：

列表 4 配置 AutoAPI#
extensions.append('autoapi.extension')
autoapi_dirs = ['../src/']  # 源代码目录
autoapi_root = 'autoapi'   # API 文档输出目录
autoapi_generate_api_docs = True

交互式代码块#

使用 thebe 扩展添加交互式代码块功能：

列表 5 配置交互式代码块#
extensions.append('sphinx_thebe')
html_theme_options.update({
    'launch_buttons': {
        'thebe': True,
    },
})
thebe_config = {
    'repository_url': 'https://github.com/yourusername/yourproject',
    'repository_branch': 'main',
    'selector': 'div.highlight',
}

实用资源#

以下是一些对使用 xyzstyle 主题和 Sphinx 文档系统有帮助的资源：

基本配置选项

包含了 xyzstyle 主题可用的基本配置选项，可直接参考使用。

Daobook sphinx

详细的 Sphinx 中文教程，帮助您深入了解文档系统。

Daobook sphinx-book-theme

xyzstyle 的父主题是 sphinx-book-theme，提供了核心主题功能。

Daobook pydata-sphinx-theme

sphinx-book-theme 的基础主题，提供了数据科学文档的专业样式。

Daobook MyST-NB

用于将 Jupyter 笔记本转换为高质量 Sphinx 文档的扩展。

Daobook MyST-Parser

支持 MyST Markdown 语法的解析器，增强 Sphinx 的 Markdown 功能。

Daobook sphinx-autoapi

自动生成 Python API 文档的扩展，无需手动编写文档字符串。

Daobook sphinx-design

提供现代化设计组件的扩展，包括卡片、标签页和网格布局。

Daobook sphinx-intl

用于 Sphinx 文档国际化和多语言翻译的工具。

开发工作流#

如果您想参与 xyzstyle 主题的开发或进行自定义修改，请按照以下步骤操作：

1. 克隆仓库#

git clone https://github.com/xinetzone/xyzstyle.git
cd xyzstyle

2. 安装开发依赖#

pip install -e '.[dev]'

3. 构建测试文档#

cd doc
sphinx-build -b html . _build/html

4. 预览文档#

您可以使用任何 HTTP 服务器来预览构建的文档：

cd _build/html
python -m http.server

然后在浏览器中访问 http://localhost:8000 查看效果。

常见问题#

如何添加自定义 CSS？#

在 conf.py 文件中配置自定义 CSS 文件：

html_static_path = ['_static']
html_css_files = [
    'css/custom.css',
]

然后在 _static/css/ 目录中创建 custom.css 文件。

如何禁用特定功能？#

您可以在 html_theme_options 中设置相应的选项为 False：

html_theme_options = {
    'use_sidenotes': False,  # 禁用侧边注释
    'back_to_top_button': False,  # 禁用返回顶部按钮
}

获取帮助#

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

目录