Sphinx阅读文档-在文本中仅使用图标

Question

我想使用一些能说明特定含义的信息性图标。将鼠标悬停在图标上，您会看到一个工具提示，显示其含义。允许非图形用户代理（例如，不支持CSS的浏览器，文本到语音设备）也可以读取它。

考虑您编写列表

• 鸡肉三明治
• 豆腐三明治-素食主义者
• 鸡肉沙拉
• 自家制沙拉-素食主义者

并且您想按以下方式进行更改，其中🥒表示“纯素”。

• 鸡肉三明治
• 豆腐三明治-🥒
• 鸡肉沙拉
• 自家色拉-🥒

我想到的一个主意是写

* Chicken sandwich
* Tofu sandwich - &&VEGAN&&
...

然后将字符串&&VEGAN&&替换为<span class="vegan">VEGAN</span>，

也添加自定义CSS代码段

span.vegan {
    display: none;
}

span.vegan:hover {
    visibility: visible;
    /* some position settings for the tool tip go here */
}

span.vegan::before {
    display: inline;
    font-family: "Font Awesome";
    content: "\f06c";
}

每次我执行make html，然后执行shell命令时，都可以完成字符串替换

find /path/to/build/html/ -name *.html -exec \
  sed -i 's/\&\&VEGAN\&\&/\<span class="vegan"\>VEGAN\<\/span\>/g' {} \;

Sphinx或Read the Docs已经具有这种功能吗？

Answer 1

创建（自定义）指令。使用replace::放置一些其他文本，使用image::放置图像，然后使用unicode::放置（特殊）Unicode字符。

在原始问题中，我希望黄瓜字符代表每个|vegan|。在相同的reStructuredText源文档中或在rst_prolog中的conf.py中创建以下指令，您可以在整个文档中应用此指令。

.. |vegan|  unicode:: U+1F952 

* Chicken sandwich
* Tofu sandwich - |vegan|
* Chicken salad
* House salad - |vegan|

运行make html，然后使用浏览器打开创建的HTML文件。您将看到如下结果：

限制：仅将指令文本替换为其他文本或图像会引起网络可访问性问题。

如原始问题所述，这些指令方法均不能具有title属性。在HTML文件中，您将要用以下HTML代码替换|vegan|：

<span title="Vegan">&#x1f952</span>

示例指令将仅生成🥒。在网络浏览器上，将鼠标悬停在黄瓜字符上，您会看到提示“ Vegan”的工具提示。即使您的浏览器不支持某些特殊字符（包括表情符号），它也可以让您查看该字符的含义。

解决方法1。仍然制作HTML并用所需的文本替换文本。查找并用HTML代码替换每个黄瓜字符。在Bash中，使用

find /path/to/build/html/ -name *.html -exec \
  sed -i 's/🥒/<span title="vegan">🥒<\/span>/g' {} \;

解决方法2对每种输出格式类型使用不同的指令。 （在研究中。有人回答StackOverflow: "Sphinx: Use a different directive for a different output format"。）