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

【问题标题】：Sphinx Read the Docs - Use icon-only in textsSphinx 阅读文档 - 在文本中仅使用图标
【发布时间】：2019-12-19 22:25:31
【问题描述】：

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

考虑你写一个列表

鸡肉三明治
豆腐三明治 - 纯素
鸡肉沙拉
自制沙拉 - 纯素

你想改变这个如下，在哪里？？？？意思是“素食主义者”。

鸡肉三明治
豆腐三明治 - ????
鸡肉沙拉
自家沙拉 - ????

我想出的一个想法是写

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

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

同时添加自定义 CSS sn-ps

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 是否已经具备此类功能？

【问题讨论】：

编写自定义 ReST 指令将是您正在寻找的明显功能。
这能回答你的问题吗？ Sphinx extension to use GitHub markdown emoji in Sphinx?
不，示例“???? To-Do”中的表情符号图标用作“装饰”，即，即使某些用户代理（例如文本到语音）无法显示这个图标，读者仍然看到文字“TO DO”。问题“豆腐三明治 - ????”中的示例是不同的。如果没有这个“信息丰富”的图标，读者就无法判断它是否是素食主义者（食物）。
@deceze - 如果您对自己的答案有信心，可以将其作为答案发布吗？ “使用信息图标，就好像它是纯图标 GUI 不是 Sphinx 2.3 版标准产品功能的一部分；您需要制作自定义 ReST 指令”。

标签： html css python-sphinx read-the-docs

【解决方案1】：

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

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

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

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

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

限制：简单地用其他文本或图像替换指令文本会留下网络可访问性问题。

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

<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"。）

【讨论】：