sphinxcontrib-svgbob

一个将ASCII图表渲染为SVG的Sphinx扩展，使用Svgbob。

🗺️ 概述

要在 Sphinx 文档中包含的图表通常使用专门的标记语言进行描述，并在构建文档时由 Sphinx 转换为图像。然而，这降低了非浏览 HTML 版本的读者对文档源的可读性。

Svgbob 是一个在 Rust 中实现的图表模型，可以将 ASCII 图表转换为 SVG。使用它可以让您

• 在文档中保留图表的文本版本，以便保持可读性。
• 以 SVG 格式渲染更美观的版本，用于文档的 HTML 或 PDF 版本。

此 Sphinx 扩展将 Svgbob 静态构建并允许您在 Sphinx 文档中使用它来渲染 ASCII 图表。由于它不需要任何外部依赖，因此也适用于在 readthedocs.org 上使用。

🔧 安装

sphinxcontrib-svgbob 可从 PyPI 安装，其中托管了一些为 x86-64 Linux 和 OSX 预构建的 CPython 轮子，以及用于从源代码编译所需代码。

$ pip install sphinxcontrib-svgbob

如果未提供 Rust 编译器，则 setup.py 脚本将尝试在 UNIX 系统上安装临时副本。如果不起作用，请参阅 rust-lang.org 上的文档 了解如何在您的机器上安装 Rust。

然后，将此扩展添加到您的 conf.py 文件中的 Sphinx 扩展，以使 svgbob 指令可用

extensions = [
    ...,
    "sphinxcontrib.svgbob",
]

这就完成了！

💡 示例

在函数文档字符串中使用 svgbob 指令来显示正在计算的图表

def hamming(x, y):
    """Compute the Hamming distance between two strings.

    Hamming distance between two strings of equal length is the number of
    positions at which the corresponding symbols are different. For instance,
    Hamming distance for a 3-bit string can be computed visually using a
    3-bit binary cube:

    .. svgbob::
       :align: center

                         110              111                          
                            *-----------*      
                           /|          /|
                          / |     011 / |     
                     010 *--+--------*  |
                         |  | 100    |  |
                         |  *--------+--* 101
                         | /         | /
                         |/          |/
                     000 *-----------*  001


    The minimum distance between any two vertices is the Hamming distance
    between the two bit vectors (e.g. 100→011 has distance 3).

    """

当 Sphinx（和 autodoc）渲染此函数的文档字符串时，您将获得以下 HTML 页面（此处显示为 readthedocs.org 的 Sphinx 主题）

而 help(hamming) 仍然看起来既美观又有用

🔩 配置

svgbob 指令支持以下参数

• font-size（整数）：要渲染的文本的大小，默认为 14。
• font-family：用于渲染文本的字体族，默认为 monospace。
• fill-color（CSS 颜色）：用于填充封闭形状的颜色。
• stroke-color（CSS 颜色）：用于绘制线条的颜色，默认为 black。
• scale（浮点数）：图形的 SVG 缩放，默认为 8.0。
• align（CSS 对齐值）：结果的图像的对齐方式。
• class（HTML 类）：添加到结果 HTML 元素的任意类。

例如，使用以下内容使用 Arial 并以 12 号大小渲染，以在图表块中渲染更美观的文本

.. svgbob::
   :font-family: Arial
   :font-size: 12

   +-------+       +--------+
   | Hello |------>| World! |
   +-------+       +--------+

💭 反馈

⚠️ 问题跟踪器

发现了一个错误？有一个增强请求？如果您需要报告或询问某些内容，请访问 GitHub 问题跟踪器。如果您正在报告错误，请尽可能提供有关问题的详细信息，并尝试在简单、易于重现的情况下重新创建相同的错误。

🏗️ 贡献

欢迎贡献！有关详细信息，请参阅 CONTRIBUTING.md。

📚 替代方案

• sphinxcontrib-kroki 也可以让您使用 Svgbob 转换 ASCII 图表，但它会查询 kroki.io 网站来完成此操作，并且不支持 Svgbob v0.5 的新选项。
• sphinxcontrib-aafig 使用 aafigure 二进制文件将 ASCII 图表转换为图像。

🔨 致谢

sphinxcontrib-svgbob 由以下人员开发和维护

• Martin Larralde

此存储库的结构是从上述 sphinxcontrib-kroki 存储库改编的，因为我没有设置 Sphinx 扩展的其他经验。

⚖️ 许可证

本库遵循MIT 许可证提供。