0

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?

Culip
  • 559
  • 8
  • 24
  • Writing a custom ReST directive would be the obvious feature you’re looking for. – deceze Dec 20 '19 at 06:05
  • Does this answer your question? [Sphinx extension to use GitHub markdown emoji in Sphinx?](https://stackoverflow.com/questions/42087466/sphinx-extension-to-use-github-markdown-emoji-in-sphinx) – Steve Piercy Dec 20 '19 at 09:42
  • No, the emoji icon in the example " To-Do" is used as "decorative", i.e., even if some user agents (e.g. text-to-speech) fail to show this icon, readers still see the text "TO DO". The example in the question "Tofu Sandwich - " is different. Without this "informative" icon readers can't tell if it is vegan (food). – Culip Dec 20 '19 at 19:12
  • @deceze - If you are confident with your answer, could you post it as an Answer? "Using informative icons as if it were icon-only GUI is not part of Sphinx' standard product feature as of version 2.3; you need to make a custom ReST directive". <- this is good enough. And of course if you have an even better answer, please post. – Culip Dec 20 '19 at 19:20

1 Answers1

0

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:

Example result on Firefox 73.

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".)

Culip
  • 559
  • 8
  • 24