Sphinx Read the Docs - Use icon-only in texts - html

Question

I want to use some informative icons that depict specific meanings. Hover your mouse over an icon and you see a tooltip showing what it means. Allow non-graphical user agents (e.g. browsers that do not support CSS, text-to-speech devices) to read it too.
Consider you write a list
Chicken sandwich
Tofu sandwich - vegan
Chicken salad
House salad - vegan
and you want to change this as below, where 🥒 means "vegan".
Chicken sandwich
Tofu sandwich - 🥒
Chicken salad
House salad - 🥒
One idea I come up with is to write
* Chicken sandwich
* Tofu sandwich - &&VEGAN&&
...
then replace the string &&VEGAN&& with <span class="vegan">VEGAN</span>,
Also add custom CSS snippets
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";
}
The string replacement can be done every time I perform make html followed by a shell command
find /path/to/build/html/ -name *.html -exec \
sed -i 's/\&\&VEGAN\&\&/\<span class="vegan"\>VEGAN\<\/span\>/g' {} \;
Does Sphinx or Read the Docs already have this sort of feature?

Answer 1

Create a (custom) directive. Use replace:: to put some other texts, image:: to put an image, and unicode:: to put a (special) Unicode character.
In the original question, I wanted the cucumber character represents every |vegan|. Create the following directive in the same reStructuredText source document or the rst_prolog in conf.py which allows you to apply this directive in entire documents.
.. |vegan| unicode:: U+1F952
* Chicken sandwich
* Tofu sandwich - |vegan|
* Chicken salad
* House salad - |vegan|
Run make html and open the created HTML file with a browser. You will see a result like below:
Restriction: Simply replacing directive texts by another texts or images will leave web accessibility concerns.
As stated in the original question, none of these directive methods can have the title attribute. In the HTML file, you will want to replace |vegan| by the following HTML code:
<span title="Vegan">&#x1f952</span>
The example directive will only makes 🥒. On a web browser, hover your mouse over the cucumber character and you will see a tooltip saying "Vegan". It will also allow you to see the meaning of this character even if your browser doesn't support some special characters including that emoji.
Workaround 1. Make HTML anyway and replace the text by a desired one. Find and replace every cucumber character by the HTML code. In Bash, use
find /path/to/build/html/ -name *.html -exec \
sed -i 's/🥒/<span title="vegan">🥒<\/span>/g' {} \;
Workaround 2. Use different directives for each output format type. (In research. Someone answer StackOverflow: "Sphinx: Use a different directive for a different output format".)