Hacer que los niveles de encabezado de los documentos dependan automáticamente de los niveles de profundidad de las (sub (sub (…))) carpetas a las que pertenecen

Question

Supongamos que tengo:

• un foo0.rstarchivo en la raíz ( source) de mi sphinx-doccarpeta de origen,
• un foo1.rstarchivo en una subcarpeta subfolder1de source,
• un foo2.rstarchivo en una subcarpeta subfolder2de subfolder1,

es decir:

$ tree source
source
├── foo0.rst
└── subfolder1
    ├── foo1.rst
    └── subfolder2
        └── foo2.rst

todos con el mismo contenido:

This a title
============

Ahora, si index.rstcontiene:

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html da:

Welcome to Test’s documentation!

Contents:

    • This a title
    • This a title
    • This a title

es decir, todos los títulos son secciones.

Lo que me gustaría obtener en su lugar es lo siguiente:

Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

ese es el encabezado de:

• foo0.rst siendo una sección,
• subfolder1/foo1.rst siendo una subsección (y no una sección),
• subfolder1/subfolder2/foo2.rst siendo una subsección (y no una sección).

Por lo tanto, mi pregunta es: ¿es posible hacer que los niveles de encabezado de los documentos que pertenecen a (sub (sub (...))) carpetas dependan automáticamente de los niveles de profundidad de las carpetas a las que pertenecen?

Answer 1

El estilo aplicado a las toctree entradas depende del tema que esté utilizando. El CSS del tema aplicará un estilo a las entradas que Sphinx tradujo <ul>y <li>dependiendo de su lugar dentro de la "jerarquía del documento", dado cómo encadena toctreesy cómo se organiza la estructura de su sección en los .rstarchivos individuales .

Por ejemplo, inspeccione los elementos HTML que genera Sphinx. El toctreeserá un div class="toctree-wrapper compound"con cada nivel de secciones que se nombrarán <li class="toctree-l1">entonces <li class="toctree-l2">, etc.

Una forma de lograr lo que desea sería rodear un determinado toctreemediante una .. class::directiva (como se muestra aquí ) y aplicar un estilo personalizado . Pero eso afectaría el estilo de cualquier otro .rstarchivo que desee incluir como entradas en eso toctree.

En cualquier caso, incurrirá en trabajo extra y potencialmente perderá automatismo si refactoriza su proyecto.

También hay una posible solución alternativa : utilizar la :hidden:opción junto con la :include:directiva. Si declara un oculto toctreeantes que un visible, toctreela "jerarquía de documentos" puede fijar la posición de una entrada para usted en la jerarquía. Posteriormente, lo visible toctreesin la :hidden:opción representará las .rstentradas del archivo como un <li>elemento que tiene una posición fija en la jerarquía. (Se puede ver un ejemplo completo en esta publicación ).

Se puede hacer, pero trabajará en contra de las características del toctree.

La solución predominante es escribir sus .rstarchivos y secciones dependiendo de cómo desee toctreeque se muestren. (Este enfoque tiene todas las ventajas con el único inconveniente de poner restricciones en la forma de escribir los .rstarchivos). Probablemente sea la solución preferible en lugar de intentar adaptar los estilos CSS o utilizar soluciones alternativas.

---

EDITAR:

Lo que escribí antes es válido, pero probablemente demasiado general. Así que daré una posible solución al ejemplo. Si quieres lo siguiente:

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

Una opción simple es usar una cadena de toctrees. Puede ocultar los toctreeque están más abajo en la jerarquía del documento si no desea verlos.

index.rst

.. toctree::
   :maxdepth: 3

   foo0

y en foo0.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

y en subfolder1/foo1.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

El resultado será el que especificó.