98

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

mzjn
  • 48,958
  • 13
  • 128
  • 248
gotgenes
  • 38,661
  • 28
  • 100
  • 128

4 Answers4

104

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • 3
    This is really beautiful. I was looking at all kinds of over-engineered solutions, including writing custom extensions before I found this. – Mad Physicist Nov 19 '15 at 15:57
  • 123
    **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."](http://www.sciencedirect.com/science/article/pii/S0019995859903626#)_) 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._) – Cecil Curry Aug 13 '16 at 04:52
  • 2
    The ["details here" link](http://docutils.sourceforge.net/docs/dev/rst/alternatives.html#nested-inline-markup) 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](https://www.gwern.net/Bitcoin-is-Worse-is-Better) enough that everything just snowballs from there(or if not at least we get good support for the unambiguous cases right away) – JamesTheAwesomeDude Aug 19 '19 at 15:56
  • 2
    be advised this only works for hyperlinks and not for intra-document links (like `:ref:`) – Jason S Feb 17 '20 at 16:29
  • Apparently here we are, ten years later, and this workaround is still required. – Leonardo Mar 28 '22 at 20:16
  • “Indefinite nesting of inline markup” is WYSIWYG formatting nightmare fuel. MS Word has that. Enforcing some limits is reasonable IMO, considering one can always extend RST like Sphinx does. – Anton Strogonoff Jun 29 '22 at 17:28
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.

Yaroslav Nikitenko
  • 1,695
  • 2
  • 23
  • 31
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • 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 '11 at 18:53
5

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.

asmeurer
  • 86,894
  • 26
  • 169
  • 240
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.

Helen
  • 87,344
  • 17
  • 243
  • 314
Kurt Krueckeberg
  • 1,225
  • 10
  • 11