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?

Solution 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.

Solution 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.