Format text by reference in reStructuredText

Question

How do you format the text in the specified link in reStructuredText?

In particular, I want to generate the following HTML from the first:

<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" part has a fixed-width font.

I tried

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

however it 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 is as follows

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

Answer 1

This design:

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

creates this HTML code (some lines are 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 understand that this is not quite what you asked for, but perhaps it is close enough. See also http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible .

Answer 2

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

 :py:class:`optparse.OptionParser` 

creates this html code:

 <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 3

Taking from the same page of frequently asked questions 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 is theoretically possible to do complex things with what cannot be done with RST.

Answer 4

If you really want to get the equivalent of HTML / CSS

 <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 as follows:

 :red:`This is red text` 

At the end of the line above, there should be only one ` . Of course you must have

 .red { color: red } 

in your CSS file.