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

python-sphinx restructuredtext

— gotgenes
źródło

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