Предотвращение вложенности подразделов в Python Sphinx при использовании toctree

Question

Я столкнулся с проблемой в структурировании моего руководства пользователя Sphinx. Я хотел бы сформировать главу, имея главную целевую страницу (index.rst), которая содержит заголовок главы и обзор, а затем отдельные подразделы, содержащиеся в разных файлах (part1.rst, part2.rst). Я пытаюсь использовать "toctree" для вставки отдельных подразделов, но я сталкиваюсь с проблемой вложения, когда мое toctree засасывается в мой обзорный раздел. (примечание: я не использую ..include:: директива, потому что я хочу, чтобы подразделы отображались на разных веб-страницах последовательно связаны между собой. Я также хочу правильно структурировать их, чтобы они хорошо выкладывались в PDF-версии UG.

index.rst

Chapter 3                                                
===============================                                                 

Overview                                                                        
--------                                                                        

Yadda yadda yadda.

.. toctree::                                                                    
   :hidden:                                                                     

   part1                                                                        
   part2

part1.rst

Part 1
------

This part is all about yadda.

part2.rst

Part 2
------

More yadda.

Я хотел бы, чтобы полученная структура была:

Chapter 3
  - overview
  - part 1
  - part 2

Но то, что я получаю,

Chapter 3
  - overview
    - part 1
    - part 2

Кажется, что toctree, который я включаю внизу файла, попадает в раздел "обзор", а не в контекст основной главы. Я попытался вставить toctree вверху файла, но затем я получаю следующий порядок:

Chapter 3
  - part 1
  - part 2
  - overview

Кажется, должен быть способ сделать это должным образом, но я не смог найти ничего на сайте Sphinx или здесь, на SO. Любая помощь приветствуется.

Answer 1

У меня была точно такая же проблема, и я не мог найти хорошее решение. Единственными вариантами, по-видимому, являются либо удаление подзаголовка ("Обзор" в приведенном выше примере), либо пометка его как рубрики, например

.. rubric:: Overview

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

Answer 2

Что касается генератора латексных PDF-файлов, вы можете просмотреть его как заголовок того же уровня, например:

.. raw:: latex

    \chapter{Overview}

Answer 3

Есть хорошее руководство по созданию пользовательской целевой страницы в Sphinx .

Идея в том, что вы создаете отдельную страницу для toc ( contents.rst) и сделайте вашу целевую страницу index.rst (или же index.html). Затем вы меняете

master_doc = 'содержимое'

в conf.py (это было index по умолчанию).