Sphinx – MySTParser – markdown: ¿Cómo permitir que cierto contenido aparezca en varias páginas?
Estamos escribiendo una documentación de Sphinx con mi equipo a partir de páginas markdown usando myst-parser (https://myst-parser.readthedocs.io/en/latest/index.html), lo cual está funcionando bastante bien.
Para evitar redundancias y mejorar el mantenimiento, nos gustaría compartir contenido entre diversas secciones de nuestra documentación de 2 maneras:
1) Listando la misma página única en 2 secciones diferentes
2) Haciendo que cierto contenido de una página aparezca en otra página.
Aquí hay algunos detalles más:
1) Cuando referencio una misma página en el índice de 2 secciones diferentes:
└── open_pages
├── common
│ └── common_page.md
├── section_1
| └── index.rst
└── section_2
└── index.rst
en donde ambos índices incluyen algo como:
<h2>Subsección</h2>
.. toctree::
/open_pages/common/common_page.md
La página aparece correctamente dos veces en el menú del lado izquierdo:
SECCIÓN 1
Common page
SECCIÓN 2
Common page
Pero si hago clic en el enlace “Common page” debajo de “SECCIÓN 1” de este menú, encuentra la página correcta pero me lleva en realidad al enlace “Common page” debajo de “SECCIÓN 2” del menú, lo cual es un poco molesto para la navegación.
¿Alguna idea de por qué ocurre esto o cómo hacerlo de manera diferente?
2) No tengo idea de cómo hacer esto, pero aquí está una descripción de lo que me gustaría:
Digamos que tengo la página1.md donde tengo esta sección y tabla:
<h2>Sección interesante</h2>
| Interesante | Tabla |
|------|------|
| ... | ... |
¿Cómo puedo incluir en la página2.md el contenido de esta sección sin copiarlo?
¡Gracias de antemano por sus consejos!
Configuración:
extensiones = [
'sphinx.ext.autosectionlabel',
'myst_parser',
'sphinx_markdown_tables'
]
autosectionlabel_prefix_document = True
- Versión de Sphinx: 3.1.2
- Versión de myst-parser: 0.15.2
davy.ai
Compartir contenido entre secciones en la documentación de Sphinx con myst-parser
Como equipo que escribe documentación Sphinx utilizando myst-parser, es posible que desee evitar la duplicación y mejorar el mantenimiento de la documentación al compartir contenido de dos formas diferentes:
1. Enumere la misma página única en 2 secciones diferentes
Para enumerar la misma página única en dos secciones diferentes, puede crear una estructura de directorio como la siguiente:
Agregue el siguiente código a ambos archivos
index.rst:Esto creará un menú en el lado izquierdo con un enlace a “Common page” en ambas “Sección 1” y “Sección 2”. Sin embargo, si hace clic en el enlace “Common page” en “Sección 1”, lo redirigirá al enlace “Common page” en “Sección 2”. Para resolver este problema, puede agregar la opción
:caption:a ambos directorestoctreede la siguiente manera:Esto mostrará “Sección 1” y “Sección 2” encima de los enlaces a “Common page” en el menú.
2. Hacer que aparezca parte del contenido de una página en otra página
Para hacer que aparezca parte del contenido de una página en otra página, puede usar la directiva
.. inclusion::en Sphinx. Digamos que tienepage1.mdcon la siguiente sección y tabla:Para incluir este contenido en
page2.md, puede agregar la siguiente línea apage2.md:Esto incluirá el contenido entre los comentarios HTML
<!-- interesting-begin -->y<!-- interesting-end -->enpage1.mdenpage2.md. Tenga en cuenta que puede reemplazar los comentarios HTML con cualquier cadena de texto única que no sea probable que aparezca en otro lugar del archivo.Esperamos que estos consejos ayuden a mejorar su documentación Sphinx. ¡Buena suerte!
Configuración: