开始使用

开始使用#

Chris Sewell

2024 年 8 月 2 日

1 分钟阅读

用法#

只需使用 pip 安装 sphinx-design 并将扩展添加到你的 conf.py

extensions = ["sphinx_design"]

对于与 MyST Parser 一起使用，用于 Markdown 文档，建议使用 colon_fence 语法扩展

extensions = ["myst_parser", "sphinx_design"]
myst_enable_extensions = ["colon_fence"]

配置#

要隐藏页面的标题头，请添加到页面顶部

---
sd_hide_title: true
---

:sd_hide_title:

创建自定义指令#

在版本 0.6.0 中添加。

你可以使用你的 conf.py 中的 sd_custom_directives 配置选项来添加自定义指令，以及默认选项值

sd_custom_directives = {
    "dropdown-syntax": {
        "inherit": "dropdown",
        "argument": "Syntax",
        "options": {
            "color": "primary",
            "icon": "code",
        },
    }
}

键是要添加的新指令名称，值是一个字典，其中包含以下键

  • inherit：要继承的指令（例如 dropdown）

  • argument：默认参数（可选，仅适用于接受单个参数的指令）

  • options：指令的默认选项字典（可选）

支持的浏览器#

  • Chrome >= 60

  • Firefox >= 60

  • Firefox ESR

  • iOS >= 12

  • Safari >= 12

  • Explorer >= 12

（镜像： twbs/bootstrap）

从 sphinx-panels 迁移#

此软件包是对 sphinx-panels 的迭代，旨在使其更灵活、更易于使用，并最大限度地减少 CSS 与 sphinx 主题的冲突。

显著变化

减少 CSS 类的直接使用#

这些被指令选项的使用所取代，它们是

  • 更易于理解

  • 更易于验证

  • 更易于处理非 HTML 输出

  • 更易于改进/重构

panel 指令已替换#

panel 指令被顶级 grid 指令的使用所取代，然后使用 grid-item-card 指令子项，而不是用 --- 分隔卡片。

如果不需要卡片，则可以使用 grid-item 指令，并且 card 也可以独立于网格使用。

大致上，.. panels:: 相当于带有 :gutter: 2 选项的 .. grid:: 1 2 2 2。

tabbed 指令已替换#

tabbed 指令被顶级 tab-set 指令的使用所取代，然后使用 tab-item 指令子项。

:sync: 选项允许跨集合同步选项卡选择。

tab-set-code 指令为同步的代码示例提供了简写形式。

octicon 图标角色#

现在生成的默认 SVG 大小与周围文本相关（即使用 1em）。指定自定义大小和添加类的语法也已更改。

这类似于 favicon 图标，其中 , 分隔符也被 ; 替换，例如 :fa:`name,class` -> :fa:`name;class` 。

改进的 CSS#

更新了 Bootstrap CSS 从 v4 -> v5，这尤其允许顶级网格定义列数和 gutter 大小。

所有 CSS 类都以 sd- 为前缀（与其他主题/扩展 CSS 无冲突）

所有颜色都使用 CSS 变量（可自定义）

目录