Formatieren Sie Text in einem Link in reStructuredText

81

Wie formatieren Sie Text innerhalb eines angegebenen Links in reStructuredText?

Insbesondere möchte ich aus meinem ersten HTML-Code Folgendes generieren:

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

Das Ergebnis sollte folgendermaßen aussehen:

optparse.OptionParser Dokumentation

Dabei befindet sich der Teil "optparse.OptionParser" in einer Schriftart mit fester Breite.

Ich habe es versucht

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

dies gab jedoch

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

das sieht so aus

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

python-sphinx restructuredtext gotgenes
quelle

Antworten:

93

Dieses Konstrukt:

Here you have |optparse.OptionParser|_.

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

erzeugt diesen HTML-Code (einige Zeilenumbrüche hinzugefügt):

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

Mir ist klar, dass dies nicht genau das ist , wonach Sie gefragt haben, aber vielleicht ist es nah genug. Siehe auch http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible .

mzjn
quelle
2
Das ist wirklich schön. Ich habe mir alle Arten von überentwickelten Lösungen angesehen, einschließlich des Schreibens benutzerdefinierter Erweiterungen, bevor ich diese gefunden habe.
Mad Physicist
91
Das ist nicht wirklich schön. Das ist schrecklich. Alle vernünftigen Markup-Sprachen unterstützen die unbestimmte Verschachtelung von Inline-Markups, da dies 2016 ist. Das kontextfreie Parsen wurde seit 1959 trivial gelöst. ( Chomsky: "Zu bestimmten formalen Eigenschaften von Grammatiken." ) Die Unfähigkeit des Parser reStructuredText, echten Kontext auszuführen -freies Parsen ist ein krasser, hässlicher Makel an einer ansonsten bravourösen Fassade. Die klar definierte und hoch erweiterbare Syntax von reST verdient es besser. ( Jemand sollte sich schlecht fühlen. )
Cecil Curry
1
Der Link "Details hier" in diesem FAQ-Eintrag ist interessant. Insbesondere "andere Formen von Inline-Markups können verschachtelt sein, wenn sie eindeutig sind". Ich frage mich, ob der einzige Weg, auf dem es passieren wird, darin besteht, dass jemand nur einen Versuch unternimmt, ein Patch-Set zu erstellen, das die eindeutigen Fälle behandelt, und dann wird dieser "leicht außerhalb der Spezifikation liegende" Geschmack von RST alltäglich genug, dass alles nur noch Schneebälle von dort sind (oder wenn nicht zumindest bekommen wir sofort gute Unterstützung für die eindeutigen Fälle)
JamesTheAwesomeDude
Bitte beachten Sie, dass dies nur für Hyperlinks und nicht für Intra-Dokument-Links (wie :ref:) funktioniert
Jason S
6

Haben Sie Intersphinx ausprobiert ? Mit dieser Erweiterung das folgende Markup:

:py:class:`optparse.OptionParser`

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

Getestet mit Python 2.6 und Sphinx 1.0.5.

mzjn
quelle
1
Ah, nun, ich wusste nichts über Intersphinx. Danke, es ist gut zu wissen. Der Link zu optparseist eigentlich nur ein Beispiel. Es geht mir wirklich darum, Text in einem Link zu einem URI zu formatieren.
Gotgenes
4

Entnehmen derselben FAQ-Seite, auf die mzjn verweist:

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>

Theoretisch sollte es möglich sein, komplizierte Dinge damit zu tun, die mit RST nicht möglich sind.

asmeurer
quelle
1
Dies funktioniert, aber es bricht auch andere Autoren (LaTeX, PDF usw.)
Jason S
0

Wenn Sie im Wesentlichen HTML / CSS-Äquivalent von erhalten möchten 

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

In reStructuredText mit Sphinx können Sie dies tun, indem Sie eine Rolle erstellen:

.. role:: red

Dann benutzt du es so:

:red:`This is red text`

Am `Ende der obigen Zeile sollte sich nur ein Häkchen befinden . Sie müssen natürlich haben 

.red { color: red }

in Ihrer CSS-Datei.

Kurt Krueckeberg
quelle