Agregar una referencia cruzada a un subtítulo o ancla en otra página


Respuestas:


207

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:

Esfinge

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.

RST, en general

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 rst2htmly desea que el archivo se A.rstvincule a una sección llamada "Sección" en el archivo other.rsty desea que el HTML final funcione en un navegador, entonces A.rstdeberí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 idserá 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 idda 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í .


9
Respuesta mucho mejor que la aceptada por el propietario de la pregunta. (¡A pesar de que RST, in Generalfue una noticia decepcionante!)
dlm

1
Una desventaja del .. _my-reference-label:enfoque Sphinx es que my-reference-labelse 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-referencey, por lo tanto, uno termina con dos #-enlaces diferentes a la misma sección.
st12

3
Y si desea darle a su enlace un nombre diferente, siempre puede usar:ref:`Link title <lmy-reference-label>`
HyperActive

52

¡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.)


5
Desde que escribí esta respuesta, he descubierto en la práctica un par de problemas con este enfoque. Primero, el cambio de nombre de las secciones es un problema. En segundo lugar, a menudo tiene títulos de sección cortos como "Más información" o "descripción general" que desea utilizar, lo que no puede hacer si está haciendo esto. Solución: agregue el título de la sección cuando / si cambia el nombre; agregue un título de sección para los títulos de sección cortos (como _page-title-learn-more). Es un poco molesto, pero todavía me gusta confiar principalmente en la autosección.
Adam Michael Wood

12
Sphinx 1.6 introduce la autosectionlabel_prefix_documentopció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.
pm

2
Esta es la mejor solución. Y el título del enlace se puede modificar fácilmente con :ref:`Link title <Internal Headline>`. Además, puede vincular directamente a una página (quickstart.rst, por ejemplo) con:doc:`quickstart`
HyperActive

5

Ejemplo:

Hey, read the :ref:`Installation:Homebrew` section.

donde Homebrewes 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.pycon lo siguiente:

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True

En 2.0.0b1 agregaron 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.
Pugsley

No necesitaba el html/prefijo
Chris
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.