Сфинкс не показывает локальные заголовки в оглавлении

Question

При создании документации sphinx с использованием настроек по умолчанию (включая тему Alabaster) на боковой панели TOC отображаются только заголовки верхнего уровня для всего документа.Используется для отображения заголовков второго уровня плюс для текущей страницы.Как я могу это исправить?

(Примечание: IIRC на это раньше влияло то, включено или нет globaltoc.html или localtoc.html в html_sidebars, но, похоже, в Alabaster и / или в последних версиях,ни один из них не существует.)

Answer 1

Оказывается, это из-за глупой и простой для просмотра настройки по умолчанию при создании нового проекта Sphinx.В частности, оглавление по умолчанию выглядит следующим образом:

.. toctree::
    :maxdepth: 1
    :caption: Contents:

    overview
    topic1
    topic2
    ...

Проблема в maxdepth.Оказывается, это не только контролирует количество уровней заголовка, которые будут отображаться в оглавлении, которое отображается в теле страницы указателя, но также также локальная глубина оглавления, отображаемая на боковой панели.По-видимому, новые проекты получают maxdepth из 1, что означает, что локальные оглавления не будут видны.