ruby tags for Sphinx/rst

Question

I create HTML documents from a rst-formated text, with the help of Sphinx. I need to display some Japanese words with furiganas (=small characters above the words), something like that :

I'd like to produce HTML displaying furiganas thanks to the < ruby > tag.

I can't figure out how to get this result. I tried to:

• insert raw HTML code with the .. raw:: html directive but it breaks my line into several paragraphs.
• use the :superscript: directive but the text in furigana is written beside the text, not above.
• use the :role: directive to create a link between the text and a CSS class of my own. But the :role: directive can only be applied to a segment of text, not to TWO segments as required by the furiganas (=text + text above it).

Any idea to help me ?

Answer 1

For raw HTML in inline context, you can generate a custom role based on the "raw" role:

.. role:: HTML(raw)
   :format: html

and use it like

你\ :HTML:`<ruby>好<rt>hǎo</rt></ruby>`\ 呀！

The backslash-escaped spaces are required so that the inline markup is recognized. (Alternatively, set the character-level-inline-markup configuration setting to True.)

Answer 2

Put the whole line, i.e., all characters including the untaged ones in the .. raw:: html directive might solve the problem. Here is an example:

.. raw:: html

    你<ruby>好<rt>hǎo</rt></ruby>呀！

Answer 3

As long as I know, there's no simple way to get the expected result.

For a specific project, I choosed not to generate the furiganas with the help of Sphinx but to modify the .html files afterwards. See the add_ons/add_furiganas.py script and the result here. Yes, it's a quick-and-dirty trick :(