Форматувати текст у посиланні в 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>\_

Відповіді:


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.


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.


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.


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.

Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.