Respuestas:
La expresión "reST / Sphinx" hace poco claro el alcance de la pregunta. ¿Se trata de reStructuredText en general y Sphinx, o solo de reStructuredText como se usa en Sphinx (y no reStructuredText en general)? Voy a cubrir ambos, ya que es probable que las personas que usan RST se encuentren con ambos casos en algún momento:
Además de las directivas específicas del dominio que se pueden usar para vincular a varias entidades como clases ( :class:
), está la :ref:
directiva general , documentada aquí . Dan este ejemplo:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Aunque el mecanismo general de hipervínculos que ofrece RST funciona en Sphinx, la documentación recomienda no usarlo cuando se usa Sphinx:
Se recomienda el uso de ref en lugar de enlaces reStructuredText estándar a secciones (como
Section title
_) porque funciona en archivos, cuando se cambian los encabezados de sección y para todos los constructores que admiten referencias cruzadas.
Las herramientas que convierten archivos RST a HTML no necesariamente tienen una noción de colección . Este es el caso, por ejemplo, si confía en github para convertir archivos RST a HTML o si usa una herramienta de línea de comandos como rst2html
. Desafortunadamente, los diversos métodos a utilizar para obtener el resultado deseado varían según la herramienta que esté utilizando. Por ejemplo, si usa rst2html
y desea que el archivo se A.rst
vincule a una sección llamada "Sección" en el archivo other.rst
y desea que el HTML final funcione en un navegador, entonces A.rst
debería contener:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
Tienes que enlazar al archivo HTML final y tienes que saber cuál id
será el dado a la sección. Si desea hacer lo mismo con un archivo servido a través de github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Aquí también necesita saber lo que se le id
da a la sección. Sin embargo, se vincula al archivo RST porque solo al acceder al archivo RST se crea el HTML. (En el momento de escribir esta respuesta, no se permite acceder directamente al HTML).
Un ejemplo completo está disponible aquí .
RST, in General
fue una noticia decepcionante!)
.. _my-reference-label:
enfoque Sphinx es que my-reference-label
se muestra en la URL después #
en el enlace. Así que hay que usar nombres de etiquetas bonitos. Además, la tabla de contenido siempre crea un #
-enlace a Section to cross-reference
y, por lo tanto, uno termina con dos #
-enlaces diferentes a la misma sección.
:ref:`Link title <lmy-reference-label>`
¡Nueva y mejor respuesta para 2016!
La extensión de autosección le permite hacer esto fácilmente.
=============
Some Document
=============
Internal Headline
=================
Entonces despúes...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
Esta extensión está incorporada, por lo que todo lo que necesita es editar conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
Lo único con lo que debe tener cuidado es que ahora no puede duplicar titulares internos en la colección de documentos. (Vale la pena.)
_page-title-learn-more
). Es un poco molesto, pero todavía me gusta confiar principalmente en la autosección.
autosectionlabel_prefix_document
opción de configuración que le permite evitar el problema de los titulares duplicados colocando el prefijo de cada etiqueta de sección con el nombre del documento del que proviene.
:ref:`Link title <Internal Headline>`
. Además, puede vincular directamente a una página (quickstart.rst, por ejemplo) con:doc:`quickstart`
Ejemplo:
Hey, read the :ref:`Installation:Homebrew` section.
donde Homebrew
es una sección dentro de un documento diferente llamado Installation.rst
.
Esto usa la función de autosección , por lo que deberá editar config.py
con lo siguiente:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth
, por lo que para que funcione la etiqueta de sección automática, debe establecer esa variable en> = 2
. Además, si se generan documentos de subdirectorio, como html
, debe anteponer árbitros con su nombre: :ref:'html/Installation:Homebrew'
. Por esta razón, es posible que desee elegir un nombre de directorio genérico, como generated
, para hacer que las referencias sean menos extrañas cuando se usan con formatos que no sean HTML. Debido a esto, también podría 'Homebrew <Installation.html#Homebrew>'__
optar por usar el reST adecuado y no estar atado a Sphinx.
html/
prefijo