Сделайте уровни заголовков документов автоматически зависимыми от уровней глубины (sub (sub (…))) папок, к которым они принадлежат

Dec 04 2020

Предположим, у меня есть:

  • 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 (...))) папкам, автоматически зависели от уровней глубины папок, к которым они принадлежат?

Ответы

1 bad_coder Dec 04 2020 at 20:37

Стиль, применяемый к 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

Результат будет таким, как вы указали.