Format text in a link in reStructuredText

Question

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>\_

Answer 1

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.

Answer 2

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.