95

How do you format text within a denoted link in reStructuredText?

Specifically, I wish to generate the following HTML from my rst:

<a href="http://docs.python.org/library/optparse.html"><tt>optparse.OptionParser</tt> documentation documentation</a>

The result should look like this:

optparse.OptionParser documentation

where the "optparse.OptionParser" portion is in fixed-width font.

I tried

```optparse.OptionParser`` <http://docs.python.org/library/optparse.html>`_

however, this gave

<tt class="docutils literal">`optparse.OptionParser</tt> documentation &lt;<a class="reference external" href="http://docs.python.org/library/optparse.html">http://docs.python.org/library/optparse.html</a>&gt;`_

which looks like this

``optparse.OptionParser documentation <http://docs.python.org/library/optparse.html>\_

4 Answers 4

102
+100

This construct:

Here you have |optparse.OptionParser|_.

.. |optparse.OptionParser| replace:: ``optparse.OptionParser`` documentation
.. _optparse.OptionParser: http://docs.python.org/library/optparse.html

produces this HTML (some linebreaks added):

<p>Here you have 
  <a class="reference external" href="http://docs.python.org/library/optparse.html">
  <tt class="docutils literal"><span class="pre">optparse.OptionParser</span></tt> documentation</a>.
</p>

I realize that this is not exactly what you asked for, but maybe it's close enough. See also http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible.

6
  • 3
    This is really beautiful. I was looking at all kinds of over-engineered solutions, including writing custom extensions before I found this. Nov 19, 2015 at 15:57
  • 120
    This is not really beautiful. This is horrible. All sane markup languages support indefinite nesting of inline markup, because this is 2016. Context-free parsing has been trivially solved since 1959. (Chomsky: "On certain formal properties of grammars.") The inability of the reStructuredText parser to perform genuine context-free parsing is a crass, ugly blemish on an otherwise sterling facade. The well-defined and highly extensible syntax of reST deserves better. (Someone should feel bad about this.) Aug 13, 2016 at 4:52
  • 2
    The "details here" link in that FAQ entry is interesting… especially “other forms of inline markup may be nested if unambiguous”; I wonder if the only way it's going to happen is if someone just takes a stab at making a patch set that handles the unambiguous cases and then this "slightly out-of-spec" flavor of RST becomes commonplace enough that everything just snowballs from there(or if not at least we get good support for the unambiguous cases right away) Aug 19, 2019 at 15:56
  • 1
    be advised this only works for hyperlinks and not for intra-document links (like :ref:)
    – Jason S
    Feb 17, 2020 at 16:29
  • Apparently here we are, ten years later, and this workaround is still required.
    – Leonardo
    Mar 28, 2022 at 20:16
7

Have you tried intersphinx? Using that extension, the following markup:

:py:class:`optparse.OptionParser`

produces this HTML:

<a class="reference external" href="http://docs.python.org/2.6/library/optparse.html#optparse.OptionParser" title="(in Python v2.6)"><tt class="xref py py-class docutils literal"><span class="pre">optparse.OptionParser</span></tt></a>

Tested with Python 2.6 and Sphinx 1.0.5.

1
  • 1
    Ah, well, I didn't know about intersphinx. Thanks, it's good to know. The link to optparse is actually just an example. I'm concerned with formatting text in a link to any URI, really.
    – gotgenes
    Jan 20, 2011 at 18:53
4

Taking from the same FAQ page referenced by mzjn:

The "raw" directive can be used to insert raw HTML into HTML output:

Here is some |stuff|.

.. |stuff| raw:: html

   <em>emphasized text containing a
   <a href="http://example.org">hyperlink</a> and
   <tt>inline literals</tt></em>

It should in theory be possible to do complicated things with that that can't be done with RST.

1
  • 1
    this works, but it also breaks other writers (LaTeX, PDF, etc.)
    – Jason S
    Dec 15, 2016 at 15:29
0

If you want to essentially do get HTML/CSS equivalent of

<span class="red">This is red text</span>

in reStructuredText using Sphinx, you can do this by creating a role:

.. role:: red

Then you use it like this:

:red:`This is red text`

There should be only one tick mark ` at the end of the line above. You, of course, have to have

.red { color: red }

in your CSS file.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.