Sformatuj tekst w linku w reStructuredText

82

Jak formatujesz tekst w oznaczonym linku w reStructuredText?

W szczególności chciałbym najpierw wygenerować następujący kod HTML:

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

Wynik powinien wyglądać następująco:

optparse.OptionParser dokumentacja

gdzie część „optparse.OptionParser” jest zapisana czcionką o stałej szerokości.

próbowałem

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

jednak to dało

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

który wygląda tak

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

gotgenes
źródło

Odpowiedzi:

93

Ta konstrukcja:

Here you have |optparse.OptionParser|_.

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

tworzy ten kod HTML (dodano kilka podziałów wierszy):

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

Zdaję sobie sprawę, że nie jest to dokładnie to, o co prosiłeś, ale może jest wystarczająco blisko. Zobacz także http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible .

mzjn
źródło
2
To jest naprawdę piękne. Patrzyłem na wszelkiego rodzaju skomplikowane rozwiązania, w tym pisanie niestandardowych rozszerzeń, zanim to znalazłem.
Mad Physicist
93
To nie jest naprawdę piękne. To jest okropne. Wszystkie rozsądne języki znaczników obsługują nieokreślone zagnieżdżanie wbudowanych znaczników, ponieważ jest to rok 2016. Analiza bezkontekstowa została rozwiązana w trywialny sposób od 1959 r. ( Chomsky: „O pewnych formalnych właściwościach gramatyki” ). Niezdolność parsera reStructuredText do wykonania prawdziwego kontekstu -bezpłatne parsowanie to prymitywna, brzydka skaza na skądinąd niezłej fasadzie. Dobrze zdefiniowana i wysoce rozszerzalna składnia reST zasługuje na coś lepszego. ( Ktoś powinien czuć się z tym źle. )
Cecil Curry
1
„Szczegółów tutaj” link do tego wpisu FAQ jest szczególnie interesujący ... „inne formy inline znacznikach mogą być zagnieżdżone jeśli jednoznaczne”; Zastanawiam się, czy jedynym sposobem, w jaki to się stanie, jest to, że ktoś po prostu spróbuje zrobić zestaw łatek, który obsługuje jednoznaczne przypadki, a wtedy ten "nieco niezgodny ze specyfikacją" smak RST staje się na tyle powszechny , że wszystko stamtąd po prostu leci śnieżkami (a jeśli nie to przynajmniej od razu otrzymujemy dobre wsparcie dla jednoznacznych przypadków)
JamesTheAwesomeDude
pamiętaj, że działa to tylko w przypadku hiperłączy, a nie łączy wewnątrz dokumentu (takich jak :ref:)
Jason S
6

Czy próbowałeś intersphinx ? Korzystając z tego rozszerzenia, następujące znaczniki:

:py:class:`optparse.OptionParser`

tworzy ten kod 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>

Przetestowano w Pythonie 2.6 i Sphinx 1.0.5.

mzjn
źródło
1
Ach, cóż, nie wiedziałem o intersphinx. Dzięki, dobrze wiedzieć. Link do optparsejest w rzeczywistości tylko przykładem. Naprawdę martwię się formatowaniem tekstu w linku do dowolnego identyfikatora URI.
gotgenes
4

Zaczerpnięte z tej samej strony FAQ, do której odwołuje się 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>

Teoretycznie powinno być możliwe zrobienie skomplikowanych rzeczy, których nie da się zrobić z RST.

asmeurer
źródło
1
to działa, ale psuje również innych pisarzy (LaTeX, PDF itp.)
Jason S,
0

Jeśli zasadniczo chcesz uzyskać odpowiednik HTML / CSS

<span class="red">This is red text</span>

w reStructuredText używając Sphinx, możesz to zrobić, tworząc rolę:

.. role:: red

Następnie używasz tego w ten sposób:

:red:`This is red text`

Na `końcu powyższej linii powinien znajdować się tylko jeden znacznik . Ty oczywiście musisz to mieć

.red { color: red }

w pliku CSS.

Kurt Krueckeberg
źródło