Сделайте уровни заголовков документов автоматически зависимыми от уровней глубины (sub (sub (…))) папок, к которым они принадлежат
Предположим, у меня есть:
foo0.rstфайл в корневом каталоге (source) моейsphinx-docисходной папки,foo1.rstфайл в папкеsubfolder1сsource,foo2.rstфайл в папкеsubfolder2сsubfolder1,
это:
$ tree source
source
├── foo0.rst
└── subfolder1
├── foo1.rst
└── subfolder2
└── foo2.rst
все с одинаковым содержанием:
This a title
============
Теперь, если index.rstсодержит:
Welcome to Test's documentation!
================================
.. toctree::
:maxdepth: 3
:caption: Contents:
foo0
subfolder1/foo1
subfolder1/subfolder2/foo2
make html дает:
Welcome to Test’s documentation!
Contents:
• This a title
• This a title
• This a title
то есть все заголовки являются разделами.
Вместо этого я хотел бы получить следующее:
Welcome to Test’s documentation!
Contents:
• This a title
◦ This a title
▪ This a title
это заголовок:
foo0.rstбудучи разделом,subfolder1/foo1.rstявляясь подразделом (а не разделом),subfolder1/subfolder2/foo2.rstявляясь подсекцией (а не разделом).
Поэтому мой вопрос: можно ли сделать так, чтобы уровни заголовков документов, принадлежащих (sub (sub (...))) папкам, автоматически зависели от уровней глубины папок, к которым они принадлежат?
Ответы
Стиль, применяемый к toctree записям , зависит от используемой вами темы . CSS темы применит стиль к записям, в которые переведен Sphinx, <ul>и в <li>зависимости от их места в «иерархии документов», учитывая то, как вы связываете toctreesи как организована ваша структура раздела в отдельных .rstфайлах.
Например, проверьте HTML-элементы, которые создает Sphinx. toctreeБудет div class="toctree-wrapper compound"с каждым уровнем секций был назван <li class="toctree-l1">тогда <li class="toctree-l2">, и т.д. ...
Один из способов добиться того, чего вы хотите, - это окружить заданное toctreeс помощью .. class::директивы (как показано здесь ) и применить собственный стиль . Но это затем повлияет на стиль любых других .rstфайлов, которые вы хотите включить в качестве записей в него toctree.
В любом случае, если вы проведете рефакторинг проекта, вам придется потратить дополнительную работу и, возможно, потерять автоматизм.
Существует также один возможный обходной путь , использующий :hidden:параметр вместе с :include:директивой. Если объявить скрытый toctreeперед видимым toctreeв «иерархии документа» может зафиксировать положение записи для вас в иерархии. Впоследствии видимый toctreeбез :hidden:опции будет отображать .rstзаписи файла как <li>элемент, имеющий фиксированную позицию в иерархии. (Подробный пример можно увидеть в этом посте ).
Это можно сделать, но вы будете работать против характеристик toctree.
Распространенным решением является написание .rstфайлов и разделов в зависимости от того, как вы хотите, toctreeчтобы они отображались. (Этот подход имеет все преимущества с единственным недостатком, заключающимся в наложении ограничений на то, как вы пишете .rstфайлы). Вероятно, это более предпочтительное решение, чем пытаться адаптировать стили CSS или использовать обходные пути.
РЕДАКТИРОВАТЬ:
То, что я писал ранее, действительно, но, вероятно, слишком общо. Итак, я приведу одно из возможных решений этого примера. Если вы хотите следующее:
Contents:
• This a title (foo0)
◦ This a title (foo1)
▪ This a title (foo2)
Простой вариант - использовать цепочку из toctrees. Вы можете скрыть те toctree, которые находятся ниже в иерархии документа, если не хотите их видеть.
index.rst
.. toctree::
:maxdepth: 3
foo0
И в foo0.rst
.. toctree::
:maxdepth: 3
:hidden:
subfolder1/foo1
И в subfolder1/foo1.rst
.. toctree::
:maxdepth: 3
:hidden:
subfolder1/subfolder2/foo2
Результат будет таким, как вы указали.