Как добавить подписи в Sphinx toctree без добавления новых документов?

Question

Хорошо, я использую Sphinx Autosummary для создания документации для некоторых классов. Есть три разных типа классов, и я хочу, чтобы моя боковая панель имела три отдельных раздела, как если бы я использовал параметр: caption: в директиве toctree.

Итак, я добавил разделенную директиву автосуммирования на три меньшие директивы, и я поместил между ними скрытое дерево маркеров, например:

Section 1

.. toctree::
   :hidden:
   :caption: Section 1

.. autosummary
   :toctree: stubs

   myclass
   anotherclass


Section 2

.. toctree::
   :hidden:
   :caption: Section 2

.. autosummary::
   :toctree:

   thirdclass

дает боковую панель вроде:

myclass
anotherclass
thirdclass

Это не работает. Иерархия моего index.html в точности такая, как я хочу, но на боковой панели отсутствуют мои подписи, они не отображаются. Когда я добавляю страницу вродеself под любым из этих скрытых toctrees появляется заголовок:

Section 1

.. toctree::
   :hidden:
   :caption: Section 1

   self

.. autosummary
   :toctree: stubs

   myclass
   anotherclass


Section 2

.. toctree::
   :hidden:
   :caption: Section 2

.. autosummary::
   :toctree:

   thirdclass

дает боковую панель вроде:

SECTION 1 (caption)
Documentation Home
myclass
anotherclass
thirdclass

Это то, что я искал, но я не хочу упоминать selfили что угодно. Мне просто нужны подписи. Как мне это сделать?

Answer 1

Цель toctreeпредназначен для организации вложенных страниц и должен иметь как минимум одну запись (имя файла). В противном случае нет никакого смысла его использовать.

Разметка ниже создает желаемую боковую панель с sphinx_rtd_theme. Я понимаю, что это не дает вам индексную страницу, которую вы хотите, но я не могу придумать другого способа сделать это. Положитеautosummary директивы в отдельные файлы и добавить каждый файл как toctree вход.

.. toctree::
   :caption: Section 1

   autosummary1

.. toctree::
   :caption: Section 2

   autosummary2