Как развернуть все подразделы на боковой панели toctree в Sphinx

Question

Мне было интересно, если есть способ расширить все подразделы под заголовками, которые включены в index.rst файл?

В качестве примера, вот как это выглядит:

Section 1
Section 2
Section 3

И вот как я бы хотел, чтобы это было:

Section 1
  Subsection 1.1
  Subsection 1.2
  Subsection 1.3
Section 2
  Subsection 2.1
  Subsection 2.2
  Subsection 2.3
Section 3
  Subsection 3.1
  Subsection 3.2
  Subsection 3.3

Если я нажимаю на Раздел 1, он показывает, что под этим, но если я нажимаю на Раздел 2, содержимое раздела 1 скрыто и отображается только 2. Мне бы хотелось, чтобы все 2 раздела расширялись каждый раз, когда я нахожусь на странице указателя. Я пытался добавить toctree а также maxdepthничего не работает.

Answer 1

Что ж, я потерял около 3,4 млн нейронов, пытаясь прочитать исходный код сфинкса (он был написан кучкой безумных безрассудных енотов?! Так много уровней абстракции).

Так:

• создайте свою собственную тему сфинкса (используйте стороннюю тему в качестве основы, очень просто. Я использую для этого "читабельную" тему)
• в каталоге, где у вас есть theme.conf, добавьте шаблон "fulltoc.html", содержащий одну строку:

fulltoc.html:

{{ toctree(collapse=False) }}

(Хех, обратите внимание на аргумент "коллапс"?)

• в sphinx conf.py измените параметр html_sidebars, чтобы добавить свой шаблон; и объявить свою тему

conf.py:

html_theme_path = [customized_readable_theme.get_html_theme_path()]
html_theme = 'customized_readable'
html_sidebars = {'**': ['fulltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}

• восстановить документацию

Answer 2

Если вы используете sphinx_rtd_theme, вы можете изменить максимальную глубину бокового меню на html-странице, изменив значение "toctree maxdepth", определенное в файле layout.html. Этот файл обычно находится в каталоге source/_themes/sphinx_rtd_theme, Есть несколько решений:

• Самое простое и быстрое решение: показать более глубокое дерево в боковой панели

• Вы используете старую версию темы. Затем вы можете установить новое значение 'maxdepth' (например, 3) в строке, которая говорит:

  {% set toctree = toctree(maxdepth=3, collapse=False, includehidden=True) %}
  

• Вы используете новейшую версию темы. Тогда у вас могут быть эти строки в файле layout.html:

  {% set global_toc = toctree(maxdepth=theme_navigation_depth|int,
                              collapse=theme_collapse_navigation|tobool,
                              includehidden=theme_includehidden|tobool,
                              titles_only=theme_titles_only|tobool) %}
  

  В этом случае вы можете определить theme_navigation_depth в theme.conf:

  [options]
  theme_navigation_depth = 3
  

Перекомпилируйте после того, как изменения сделаны... и не забудьте насладиться солнцем!

Answer 3

К сожалению, по этому поводу есть открытая ошибка:https://github.com/readthedocs/sphinx_rtd_theme/issues/455

Answer 4

Вот как это можно сделать для мобильной темы sphinx_rtd_theme.

Добавьте в свой пользовательский JavaScript следующий [Vanilla] JS:

      function toctreeExpand ()
{var toctree=document.querySelector('button.toctree-expand');

 toctree.focus ();
 toctree.click ();
} // function toctreeExpand ()                                                                

function deferToctreeExpand ()
{// flush any pending housekeeping events first...                                            
 setTimeout (toctreeExpand);
} // function deferToctreeExpand ()                                                           

function init ()
{var anchors=document.querySelectorAll('a.reference.internal');

 toctreeExpand ();
 for (var anchor of anchors)
     anchor.addEventListener ('click', deferToctreeExpand);
} // function init ()                                                                         

window.addEventListener ('load', init);

Он расширяет только записи верхнего уровня, но это чертовски лучше, чем по умолчанию, показывающее дерево полностью свернутым как одну запись! Это можно улучшить, (повторно) развернув вложенную ветку, где вы только что щелкнули (возможно, на три уровня ниже...). Но у меня полный почтовый ящик; поэтому указанное выше исправление было приемлемым для меня...