Tornar os níveis de título de documentos automaticamente dependentes dos níveis de profundidade das (sub (sub (...)) pastas às quais pertencem

Dec 04 2020

Suponha que eu tenha:

  • um foo0.rstarquivo na raiz ( source) da minha sphinx-docpasta de origem,
  • um foo1.rstarquivo em uma subpasta subfolder1de source,
  • um foo2.rstarquivo em uma subpasta subfolder2de subfolder1,

isso é:

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

todos com o mesmo conteúdo:

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

Agora, se o index.rstcontém:

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

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

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html dá:

Welcome to Test’s documentation!

Contents:

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

isto é, todos os títulos são seções.

O que eu gostaria de obter em vez disso é o seguinte:

Welcome to Test’s documentation!

Contents:

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

esse é o título de:

  • foo0.rst sendo uma seção,
  • subfolder1/foo1.rst sendo uma subseção (e não uma seção),
  • subfolder1/subfolder2/foo2.rst sendo uma subseção (e não uma seção).

Portanto, minha pergunta é: é possível fazer os níveis de título de documentos pertencentes a (sub (sub (...))) pastas dependerem automaticamente dos níveis de profundidade das pastas a que pertencem?

Respostas

1 bad_coder Dec 04 2020 at 20:37

O estilo aplicado às toctree entradas depende do tema que você está usando. O CSS do tema aplicará um estilo às entradas para as quais o Sphinx traduziu <ul>e <li>dependendo de seu lugar na "hierarquia de documentos", considerando como você encadeia toctreese como sua estrutura de seção nos .rstarquivos individuais é organizada.

Por exemplo, inspecione os elementos HTML gerados pelo Sphinx. O toctreeserá um div class="toctree-wrapper compound"com cada nível de seções sendo nomeado <li class="toctree-l1">então <li class="toctree-l2">, etc ...

Uma maneira de conseguir o que você deseja seria cercar um dado toctreeusando uma .. class::diretiva (como mostrado aqui ) e aplicar um estilo personalizado . Mas isso afetaria o estilo de quaisquer outros .rstarquivos que você deseja incluir como entradas nele toctree.

Em qualquer caso, você incorrerá em trabalho extra e automatismo potencialmente perdido se refatorar seu projeto.

Também existe uma solução alternativa possível , usando a :hidden:opção junto com a :include:diretiva. Se você declarar um oculto toctreeantes de um visível, toctreea "hierarquia de documentos" pode fixar a posição de uma entrada para você na hierarquia. Posteriormente, o visível toctreesem a :hidden:opção renderizará .rstas entradas do arquivo como um <li>elemento com uma posição fixa na hierarquia. (Um exemplo completo pode ser visto neste post ).

Isso pode ser feito, mas você estará trabalhando contra as características do toctree.

A solução predominante é gravar seus .rstarquivos e seções dependendo de como você deseja que eles toctreesejam exibidos. (Essa abordagem tem todas as vantagens com a única desvantagem de colocar restrições sobre como você grava os .rstarquivos). Provavelmente é a solução preferível em vez de tentar adaptar os estilos CSS ou usar soluções alternativas.


EDITAR:

O que escrevi antes é válido, mas provavelmente muito geral. Portanto, darei uma solução possível para o exemplo. Se você deseja o seguinte:

Contents:

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

Uma opção simples é usar uma cadeia de toctrees. Você pode ocultar os toctreeque estão mais abaixo na hierarquia do documento se não quiser vê-los.

index.rst

.. toctree::
   :maxdepth: 3

   foo0

e em foo0.rst

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

   subfolder1/foo1

e em subfolder1/foo1.rst

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

   subfolder1/subfolder2/foo2

O resultado será o que você especificou.