Sphinx добавляет заголовки из файла разметки в структуру документа

Question

Я настроил Sphinx для использования файлов уценки.

В моем файле index.rst у меня есть

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   documents/Markdown

В Markdown.md у меня есть

# Markdown

## H2 Heading

При рендеринге главной страницы появляется заголовок H2в toctree.

У меня есть другие части моего дерева, где я хочу: maxdepth больше 1. Почему сфинкс читает заголовок H2как часть toctree, и как я могу заставить его прекратить это делать, не устанавливая: maxdepth в 1?

Answer 1

@ mzjn частично отвечает на ваш запрос.Лично я не уверен, как именно это делается в Markdown, но я предполагаю, что это похоже на reStructuredText.К сожалению, на данный момент нет интуитивно понятного способа сделать это.Однако вы можете сделать следующее:

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

Это выведет желаемое поведение, но в этом случае у вас будет вертикальный интервал между двумя деревьями.Либо вы делаете это, либо можете использовать:

.. toctree::
   :maxdepth: 2

   documents/Markdown1
   documents/Markdown2

Но вам нужно будет перенести то, что вы не хотите показывать, на более низкий уровень (например, H3).

Answer 2

Опция maxdepth указывает требуемую глубину оглавления.

Если вы используете :maxdepth: 1, «заголовок H2» должен исчезнуть.