Sphinx-Design 使用教程

Sphinx-Design 使用教程

项目介绍

Sphinx-Design 是一个用于设计美观、屏幕尺寸响应式网页组件的 Sphinx 扩展。它受到 Bootstrap (v5)、Material Design 和 Material-UI 设计框架的启发，旨在为 Sphinx 文档提供丰富的 UI 组件。

项目快速启动

安装

首先，通过 pip 安装 sphinx-design 扩展：

pip install sphinx-design

配置

在 Sphinx 项目的 conf.py 文件中添加扩展：

extensions = [
    "sphinx_design"
]

示例

以下是一个简单的卡片组件示例：

.. card:: Card Title
   :class: my-class

   Card content

应用案例和最佳实践

单卡片示例

.. card:: 单卡片标题

   这是单卡片的内容。

网格卡片示例

.. grid:: 1 2 3 4
   :gutter: 1

   .. grid-item-card:: 卡片1
      :link: https://example.com

      这是卡片1的内容。

   .. grid-item-card:: 卡片2
      :link: https://example.com

      这是卡片2的内容。

最佳实践

• 响应式设计：确保所有组件在不同屏幕尺寸下都能良好显示。
• 可配置性：利用 CSS 变量配置颜色和其他样式，以适应不同的主题需求。

典型生态项目

sphinx-copybutton

sphinx-copybutton 是一个用于添加复制按钮到代码块的 Sphinx 扩展。

sphinx-tabs

sphinx-tabs 允许在 Sphinx 文档中创建可切换的标签页。

jupyter-sphinx

jupyter-sphinx 可以在 Sphinx 文档中嵌入 Jupyter 笔记本的内容。

通过这些扩展，可以进一步增强 Sphinx 文档的功能和交互性。