Dar formato al texto de un enlace en reStructuredText

81

¿Cómo se formatea el texto dentro de un enlace indicado en reStructuredText?

Específicamente, deseo generar el siguiente HTML a partir de mi primera:

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

El resultado debería verse así:

optparse.OptionParser documentación

donde la parte "optparse.OptionParser" está en una fuente de ancho fijo.

Lo intenté

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

sin embargo, esto dio

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

que se ve así

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

python-sphinx restructuredtext gotgenes
fuente

Respuestas:

93

Esta construcción:

Here you have |optparse.OptionParser|_.

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

produce este HTML (se agregaron algunos saltos de línea):

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

Me doy cuenta de que esto no es exactamente lo que pediste, pero tal vez esté lo suficientemente cerca. Consulte también http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible .

mzjn
fuente
2
Esto es realmente hermoso. Estaba buscando todo tipo de soluciones de ingeniería, incluida la escritura de extensiones personalizadas antes de encontrar esto.
Mad Physicist
91
Esto no es realmente hermoso. Esto es horrible. Todos los lenguajes de marcado cuerdos admiten el anidamiento indefinido de marcado en línea, porque estamos en 2016. El análisis sintáctico sin contexto se ha resuelto trivialmente desde 1959. ( Chomsky: "Sobre ciertas propiedades formales de las gramáticas" ). La incapacidad del analizador reStructuredText para realizar un contexto genuino -El análisis libre es una mancha grosera y fea en una fachada por lo demás excelente. La sintaxis bien definida y altamente extensible de reST merece algo mejor. ( Alguien debería sentirse mal por esto )
Cecil Curry
1
El enlace "detalles aquí" en esa entrada de preguntas frecuentes es interesante ... especialmente "otras formas de marcado en línea pueden estar anidadas si no son ambiguas"; Me pregunto si la única forma en que va a suceder es si alguien intenta crear un conjunto de parches que maneje los casos inequívocos y luego este sabor "ligeramente fuera de especificación" de RST se vuelve lo suficientemente común como para que todo salga como una bola de nieve a partir de ahí. (o si no al menos obtenemos un buen apoyo para los casos inequívocos de inmediato)
JamesTheAwesomeDude
tenga en cuenta que esto solo funciona para hipervínculos y no para enlaces dentro del documento (como :ref:)
Jason S
6

¿Has probado la interesfinge ? Usando esa extensión, el siguiente marcado:

:py:class:`optparse.OptionParser`

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

Probado con Python 2.6 y Sphinx 1.0.5.

mzjn
fuente
1
Ah, bueno, no sabía nada de la interesfinge. Gracias, es bueno saberlo. En optparserealidad, el enlace a es solo un ejemplo. Realmente me preocupa formatear el texto en un enlace a cualquier URI.
gotgenes
4

Tomando de la misma página de preguntas frecuentes a la que hace referencia 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>

En teoría, debería ser posible hacer cosas complicadas con eso que no se pueden hacer con RST.

como medidor
fuente
1
esto funciona, pero también rompe a otros escritores (LaTeX, PDF, etc.)
Jason S
0

Si desea esencialmente obtener HTML / CSS equivalente a 

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

en reStructuredText usando Sphinx, puede hacer esto creando un rol:

.. role:: red

Entonces lo usas así:

:red:`This is red text`

Debe haber solo una marca de verificación `al final de la línea anterior. Tu, por supuesto, tienes que tener 

.red { color: red }

en su archivo CSS.

Kurt Krueckeberg
fuente