¿Cómo insertar una referencia cruzada en una página reST / Sphinx a un subencabezado o un ancla en otra página en el mismo conjunto de documentación?

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

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

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