如何为Sphinx-RTD-theme添加自定义图标？求实例

完全可以给Sphinx（包括Sphinx-RTD-theme）添加自定义图标，下面是具体实现步骤和实例：

1. 准备图标文件 #

把你的自定义图标（优先选SVG格式，矢量清晰适配各种尺寸）放到文档目录的_static/icons/下，没有这个目录就手动创建。比如我准备了my-logo.svg和feature-icon.png两个图标。

2. 添加自定义CSS样式 #

在_static/目录下创建custom.css文件，定义图标的样式类：

/* 自定义图标基础样式 */
.icon-custom {
    display: inline-block;
    width: 16px;  /* 和RTD主题默认图标尺寸对齐 */
    height: 16px;
    margin-right: 4px;
    background-size: contain;
    background-repeat: no-repeat;
    vertical-align: middle;  /* 让图标和文字居中对齐 */
}

/* 对应不同图标的类 */
.icon-my-logo {
    background-image: url('icons/my-logo.svg');
}

.icon-feature {
    background-image: url('icons/feature-icon.png');
}

3. 在Sphinx配置中引入自定义CSS #

打开conf.py，确保html_static_path和html_css_files包含你的自定义CSS：

import os
import sys

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

# 如果你用的是Sphinx-RTD-theme，确保主题配置正确
html_theme = 'sphinx_rtd_theme'

4. 在文档中使用自定义图标 #

方法1：直接用HTML标签（简单快捷） #

在.rst文件中直接插入HTML span标签：

<span class="icon-custom icon-my-logo"></span> 这是带自定义图标的标题

- <span class="icon-custom icon-feature"></span> 带自定义图标的列表项

方法2：自定义RST指令（更优雅，适合频繁使用） #

如果需要频繁使用图标，可以自定义RST指令避免重复写HTML：

1. 在文档目录下创建_extensions目录，新建custom_icons.py文件：

from docutils import nodes
from docutils.parsers.rst import Directive

class CustomIcon(Directive):
    required_arguments = 1  # 需要传入图标类名

    def run(self):
        icon_name = self.arguments[0]
        # 生成对应的HTML标签
        icon_node = nodes.raw(
            '',
            f'<span class="icon-custom icon-{icon_name}"></span>',
            format='html'
        )
        return [icon_node]

def setup(app):
    app.add_directive('icon', CustomIcon)
    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

2. 在conf.py中注册这个扩展：

# 添加_extensions目录到路径
sys.path.insert(0, os.path.abspath('_extensions'))

extensions = [
    # 你的其他扩展（比如sphinx.ext.autodoc等）
    'custom_icons',
]

3. 之后在.rst文件中就可以这样用：

.. icon:: my-logo
这是带自定义图标的内容

- .. icon:: feature
  带自定义图标的列表项

注意事项 #

• 确保图标文件路径正确，CSS中的路径是相对于_static目录的
• 可根据文档风格调整CSS中的width、height和margin参数
• SVG图标支持无损缩放，优先选择SVG格式；如果用PNG，建议准备2x分辨率版本适配高DPI屏幕

内容的提问来源于stack exchange，提问作者user1255603