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

sphinx search

Question

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

Answer 1

La expresión "reST / Sphinx" hace que el alcance de la pregunta no sea claro. ¿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 las personas que usan RST probablemente se topen con ambos casos en algún momento:

Esfinge

Además de las directivas específicas de dominio que se pueden usar para vincular a varias entidades como clases ( :class: existe la directiva general :ref: documentada here . Ellos 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 ofrecido por RST funciona en Sphinx, la documentación recomienda no usarlo cuando se usa Sphinx:

Se recomienda usar ref por enlaces de texto reStructured estándar a secciones (como Section title _) porque funciona en todos los archivos, cuando se cambian los títulos de las secciones 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ías en github para convertir archivos RST a HTML o si usas una herramienta de línea de comandos como rst2html . Lamentablemente, los diversos métodos que se utilizan para obtener el resultado deseado varían según la herramienta que esté utilizando. Por ejemplo, si usa rst2html y quiere que el archivo 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 contendrá:

`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 vincular al archivo HTML final y debes saber cuál será la id dará a la sección. Si desea hacer lo mismo para 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 la id dio a la sección. Sin embargo, se vincula al archivo RST porque solo al acceder al archivo RST se crea el HTML. (Al momento de escribir esta respuesta, no se permite el acceso al HTML directamente).

Un ejemplo completo está disponible here .

Answer 2

¡Nueva, mejor respuesta para 2016!

La extensión de autoselección te 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 que debe tener cuidado es que ahora no puede duplicar los titulares internos en la colección de documentos. (Vale la pena.)

Answer 3

Ignora esta respuesta, no funciona: es mejor utilizar la respuesta de Louis

Para el anclaje, puede definir nombres de anclaje "cortos" como este:

.. _ShortAnchor:
Target Header goes here
=======================
Some text.

Para referirse a ese encabezado use:

For more details, see ShortAnchor_.

Tenga en cuenta que esto incluso expande ShortAnchor al nombre completo del encabezado.

También puede usar el nombre completo del encabezado como:

See `Target Header goes here`_ chapter.

Pero esto es más propenso a errores en la modificación del texto del encabezado.

Todo esto funciona en múltiples archivos fuente que forman parte de una documentación final.