How to underline text in reStructuredText?

Question

Of course, on the web an underline denotes hyperlink, but what if I need underline which is not a hyperlink?

Uella

Answer 1

I asked a similar question here. Try like this:

.. role:: underline
    :class: underline

In the document, this can be applied as follows:

:underline:`This text is underlined`

In your css file you could have:

.underline {
  text-decoration: underline;
}

This should work for HTML output. However, underlining is intentionally not part of the ReST specs. See this link.

Morgenthaler

While I understand that "_" would be bad for underlining in python, but David Ascher (in the link) just written crap. "no well-typeset book ever uses underlines"? Who cares if underlining was used for indicating italics in classic typset? Do I care how ancient egyptians used something that possibly looks like a road sign? No. Because we are well past that point, and the sign is freed from that old meaning... For example in Hungarian schools, underlining is frequently used for indicating results in assignment. It comes from hand-written text as well. – Borries

I too aspire to underline text. Villain, reprobate, contradictory, rebel they call me. I am none of those things. I know the true way. Rules no longer bind you when you know the truth. – Foeticide

You don't need the :class: option in this case. The role name becomes a class value by default. – Gabriellia

Answer 2

You add the following directive in the index.rst file for example:

.. role:: underline
    :class: underline

In the document you indicate the text as underlined with the following:

:underline:`This text is underlined`

To specify the css for your underline class you add some css to the layout.html file inside the folder _themes/sphinx_rtd_theme/sphinx_rtd_theme/ if you are using the sphinx_rtd_theme, otherwise your default theme directory:

<style>
    .underline {
    text-decoration: underline;
  }
</style>

This will style your html accordingly.

Underlining is part of the StructureText but not of Sphinx's reStructuredText specifications, according to a quote from David Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring grammar: a very revised proposal":

The tagging of underlined text with _'s is suboptimal. Underlines shouldn't be used from a typographic perspective (underlines were designed to be used in manuscripts to communicate to the typesetter that the text should be italicized -- no well-typeset book ever uses underlines), and conflict with double-underscored Python variable names (init and the like), which would get truncated and underlined when that effect is not desired. Note that while complete markup would prevent that truncation ('init'), I think of docstring markups much like I think of type annotations -- they should be optional and above all do no harm. In this case the underline markup does harm.

Mccreary

Answer 3

If you want to mark up inserted text parts, define and use an "ins" role:

.. role:: ins

The "ins" role is by default rendered as underlined :ins:`in HTML5, 
where the <ins> tag is used`.

Gabriellia