Использование self для создания карты сайта с toctree в sphinx кажется неправильным?

Question

Я обновляю часто задаваемые вопросы для довольно большого проекта, и я хотел бы добавить индекс вопросов вверху страницы, чтобы пользователям стало легче находить то, что они ищут.

В статье toctree в документации Sphinx говорится: "Специальное имя записи self обозначает документ, содержащий директиву toctree. Это полезно, если вы хотите сгенерировать" карту сайта "из toctree". Это то, что я хочу. Проблема в том, что self кажется испорченным и включает только название текущего документа, а не субтитры. Он работает правильно, когда я нахожусь в другом документе и ссылается на часто задаваемые вопросы, только в самом документе это не удается.

Показывать

.. toctree::
   :maxdepth: 3

   faq

В другом файле результаты в

• Часто задаваемые вопросы
  • Часто задаваемые вопросы
    • Вопрос 1
    • вопрос 2
    • Вопрос 3
  • Неочевидное поведение и другое нужно знать

Внутри faq

.. toctree::
   :maxdepth: 3

   self

результаты в

• Часто задаваемые вопросы

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

Будем весьма благодарны за любые идеи о том, как включить индекс страницы в саму страницу с помощью sphinx.

Answer 1

То, что вы ищете, это директива содержимого.

Вставьте следующий блок после заголовка вашей страницы, чтобы составить список вопросов:

.. contents::
   :local:
   :depth: 1

Это произведет:

• Вопрос 1
• вопрос 2
• Вопрос 3