Tornar os níveis de título de documentos automaticamente dependentes dos níveis de profundidade das (sub (sub (...)) pastas às quais pertencem
Suponha que eu tenha:
- um
foo0.rst
arquivo na raiz (source
) da minhasphinx-doc
pasta de origem, - um
foo1.rst
arquivo em uma subpastasubfolder1
desource
, - um
foo2.rst
arquivo em uma subpastasubfolder2
desubfolder1
,
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.rst
conté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
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 toctrees
e como sua estrutura de seção nos .rst
arquivos individuais é organizada.
Por exemplo, inspecione os elementos HTML gerados pelo Sphinx. O toctree
será 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 toctree
usando uma .. class::
diretiva (como mostrado aqui ) e aplicar um estilo personalizado . Mas isso afetaria o estilo de quaisquer outros .rst
arquivos 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 toctree
antes de um visível, toctree
a "hierarquia de documentos" pode fixar a posição de uma entrada para você na hierarquia. Posteriormente, o visível toctree
sem a :hidden:
opção renderizará .rst
as 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 .rst
arquivos e seções dependendo de como você deseja que eles toctree
sejam exibidos. (Essa abordagem tem todas as vantagens com a única desvantagem de colocar restrições sobre como você grava os .rst
arquivos). 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 toctree
s. Você pode ocultar os toctree
que 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.