python sphinx - traduccion - ¿Cómo puedo enlazar a una sección de página en un toctree de esfinge?

sphinx traduccion

Question

Tengo un .. toctree como parte de una página de esfinge, que incluye enlaces relativos a otros archivos de rst en mi paquete. ¿Cómo puedo incluir un enlace a una subsección de una página determinada, en lugar de la página completa?

Probé

.. toctree::

   page#section

Pero eso no funcionó. Cualquier ayuda es genial.

Answer 1

Al crear el ToC, Sphinx incluye todos los encabezados y subtítulos de los archivos de referencia dentro de la profundidad del árbol configurado. Por lo tanto, simplemente no puede comenzar la página con un encabezado e insertar el encabezado en el punto al que desea que apunte el ToC, por ejemplo:

.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive

And here some more text, normal font weight.

Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...

Debe incluir la referencia de la página en el ToC como de costumbre. Así que en el ToC, tienes:

.. toctree::

   my_rst_file

En nuestro ejemplo, el resultado de la compilación (HTML, PDF, lo que sea) solo tendrá una referencia a Here comes the heading that will appear in the ToC en el ToC.

Answer 2

Después de mucha piratería, he llegado a la siguiente solución, pero primero debo decir que mi objetivo era:

1. hacer que el encabezado NO aparezca en el cuerpo del contenido
2. hacer que el encabezado aparezca en la tabla de contenido

Así que básicamente se vincula desde la TOC a una parte arbitraria pero invisible de un documento.

Necesitaba esto para poder vincular a métodos en alguna documentación de código fuente presentada con Sphinxcontrib PHPDomain: estos métodos generan enlaces de sección propios, pero no se agregan a la TOC de forma predeterminada.

Paso 1:

En la parte superior de su archivo RST que necesita esta funcionalidad de enlace, agregue una nueva función como tal:

.. role:: hidden
   :class: hidden

Paso 2:

En algún lugar del contenido, usa este rol como tal:

:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""

Paso 3:

Agregue un nuevo CSS al proyecto (por lo general, agregando un archivo CSS a _static , o definiendo una hoja de estilo o algo así, vea this ):

.rst-content .hidden {
    display: none;
}

nav .hidden {
    display: unset;
}

Esto obliga a que el encabezado se oculte en el contenido, pero se muestre en la tabla de contenido.

Luego, reutilice el rol según sea necesario en otros documentos.

Tenga en cuenta que si su objetivo es enlazar a ubicaciones arbitrarias en el documento y aún mostrar los encabezados en el contenido, simplemente cambie el CSS para adaptar los encabezados a su gusto en lugar de ocultarlos.