xyzstyle

xyzstyle#

PyPI GitHub issues GitHub forks GitHub stars GitHub license contributors watcher Binder Downloads Documentation Status PyPI - Downloads repo size Downloads Week

xyzstyle 是一款精心设计的基于 Sphinx 的文档主题，旨在提供美观、专业且易于使用的文档展示解决方案。该主题基于 sphinx-book-theme 进行定制，注重用户体验和视觉设计，同时保持了良好的可访问性和可定制性。

主题特点#

  • 现代化界面设计：简洁清晰的布局，专业的配色方案

  • 完善的响应式支持：适配各种设备屏幕尺寸

  • 丰富的内容展示：支持Markdown、Jupyter笔记本等多种内容格式

  • 国际化支持：内置多语言翻译机制

  • 易于定制：提供多种配置选项满足不同需求

安装并激活主题#

安装步骤#

使用 Python 的包管理工具 pip 安装 xyzstyle：

pip install xyzstyle

如需安装特定版本，可以使用：

pip install xyzstyle==版本号

开发模式安装（可编辑模式）#

如果您需要对主题进行开发或修改，可以使用可编辑模式安装：

# 首先进入项目根目录
cd xyzstyle项目路径
# 然后以可编辑模式安装
pip install -ve .

其中参数含义：

  • -v 表示详细输出

  • -e 表示可编辑模式（开发模式）

  • . 表示当前目录

这种安装方式会在安装包时创建一个指向源代码的链接，使您对源码的修改能够立即反映到已安装的包中，无需重新安装。

激活主题#

安装完成后，需要在您的 Sphinx 项目配置文件（通常为 conf.py ）中进行设置以激活主题：

# == 项目基本信息 ========================================================================
project = 'xyzstyle' # 项目名称
copyright = '2022, xinetzone' # 版权信息
author = 'xinetzone' # 作者信息

# == 主题设置 ============================================================================
html_theme = "xyzstyle" # 使用的HTML主题
# 静态资源配置
html_static_path = ['_static']  # 指定静态文件目录，用于存放CSS、JavaScript、图片等
html_logo = "_static/images/logo.jpg"  # 网站Logo路径，显示在页面顶部
html_favicon = "_static/images/favicon.jpg"  # 网站图标路径，显示在浏览器标签页
html_last_updated_fmt = '%Y-%m-%d, %H:%M:%S'  # 最后更新时间格式

# == 国际化与本地化设置 ==================================================================
language = 'zh_CN' # 文档语言（中文简体）
locale_dirs = ['../locales/'] # 翻译文件存放目录
gettext_compact = False # 是否合并子目录的PO文件（False表示不合并）

# == 扩展插件配置 ========================================================================
extensions = [
    "myst_nb",  # Markdown和Jupyter笔记本支持
] # 启用的Sphinx扩展

通过设置 html_theme = "xyzstyle" 即可在您的项目中激活 xyzstyle 主题，使生成的文档采用该主题的样式和布局。

其他选项#

# 主题选项配置
html_theme_options = {
    "use_sidenotes": True,        # 启用侧边注释/页边注释
    "repository_url": "https://github.com/yourusername/yourproject",  # 仓库地址
    "use_repository_button": True,  # 显示"在 GitHub 上查看"按钮
    "announcement": "欢迎使用 xyzstyle 主题！",  # 公告横幅
    "use_source_button": True,      # 显示"查看源代码"按钮
    "use_edit_page_button": True,   # 显示"编辑此页"按钮
    "use_issues_button": True,      # 显示"报告问题"按钮
    "path_to_docs": "doc",          # 文档目录路径
}
# 可选插件
extensions.extend([
    "sphinx_design",                # 增强设计元素
    "sphinx.ext.viewcode",          # 添加到高亮源代码的链接
    "sphinx.ext.intersphinx",       # 链接到其他文档
    "sphinx_copybutton",            # 为代码块添加复制按钮
    "sphinx_comments",              # 添加评论和注释功能
])
# =============================================================================
# 可选功能配置
# =============================================================================
# 1. 代码复制按钮配置
copybutton_exclude = '.linenos, .gp'  # 排除行号和提示符
# 选择器配置，避免复制按钮出现在笔记本单元格编号上
copybutton_selector = ":not(.prompt) > div.highlight pre"

# 2. 评论系统配置
comments_config = {
   "hypothesis": True,  # 启用 Hypothesis 注释
   "utterances": {
      "repo": "xinetzone/xyzstyle",
      "optional": "config",
   }  # 启用 Utterances 评论
}

可以添加自定义图标链接，例如社交媒体图标、GitHub徽章或项目标志：

# 在conf.py文件的开头添加
from utils.links import icon_links  # 或者直接定义

# 自定义图标链接
html_theme_options.update({
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/yourusername/yourproject",
            "icon": "fab fa-github",
            "type": "fontawesome",
        },
        {
            "name": "Twitter",
            "url": "https://twitter.com/yourusername",
            "icon": "fab fa-twitter",
            "type": "fontawesome",
        },
        # 更多图标链接...
    ],
})

启动按钮配置#

添加交互式代码演示启动按钮：

html_theme_options.update({
    "repository_branch": "main",
    "launch_buttons": {
        "binderhub_url": "https://mybinder.org",
        "colab_url": "https://colab.research.google.com/",
        "deepnote_url": "https://deepnote.com/",
        "notebook_interface": "jupyterlab",
        "thebe": True,
    },
})

# Thebe 配置
thebe_config = {
    "repository_url": "https://github.com/yourusername/yourproject",
    "repository_branch": "main",
    "selector": "div.highlight",
}

自定义样式#

可以通过添加自定义CSS文件来覆盖默认样式：

# 添加自定义CSS文件
html_static_path = ['_static']
html_css_files = ["css/custom.css"]

然后在 _static/css/custom.css 文件中添加自定义样式：

/* 自定义公告横幅样式 */
.announcement {
    background-color: #4078c0;
    color: white;
    padding: 10px 0;
    text-align: center;
}

/* 自定义代码块样式 */
div.highlight {
    border-radius: 5px;
}

/* 更多自定义样式... */

下一步#

配置完成后，您可以使用标准的 Sphinx 命令生成文档：

# 基本文档生成命令
sphinx-build -b html 源目录 输出目录

# 例如
sphinx-build -b html doc/source doc/build/html

生成的文档将使用 xyzstyle 主题的样式呈现，为您的项目提供专业、美观的文档界面。

项目目录结构#

xyzstyle/
├── src/                  # 源代码目录
│   └── xyzstyle/         # 主题源码
│       ├── __init__.py   # 主题初始化文件
│       └── theme/        # 主题模板和样式
│           └── xyzstyle/ # 主题文件
├── doc/                  # 文档目录
│   ├── conf.py           # Sphinx配置文件
│   └── ...               # 其他文档源文件
├── pyproject.toml        # 项目配置和依赖
├── LICENSE               # 许可证文件
└── README.md             # 项目说明文档

开发指南#

安装开发依赖#

# 安装开发依赖
pip install -e "[dev]"

# 或安装文档构建依赖
pip install -e "[doc]"

构建文档#

# 进入文档目录
cd doc

# 构建文档
sphinx-build -b html . _build/html

目录和索引#

目录