Форматувати текст у посиланні в reStructuredText

82

Як відформатувати текст у позначеному посиланні в reStructuredText?

Зокрема, я хочу створити такий HTML з мого першого:

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

Результат повинен виглядати так:

optparse.OptionParser документація

де частина "optparse.OptionParser" має шрифт фіксованої ширини.

я намагався

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

проте це дало

<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;`_

що виглядає так

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

python-sphinx restructuredtext

— gotgenes
джерело

93

Ця конструкція:

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
джерело

2

This is really beautiful. I was looking at all kinds of over-engineered solutions, including writing custom extensions before I found this.

— Mad Physicist

92

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

— Cecil Curry

1

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)

— JamesTheAwesomeDude

be advised this only works for hyperlinks and not for intra-document links (like :ref:)

— Jason S

6

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.

— mzjn
джерело

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

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.

— asmeurer
джерело

1

this works, but it also breaks other writers (LaTeX, PDF, etc.)

— Jason S

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.

— Kurt Krueckeberg
джерело