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

Question

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

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

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

   documents/Markdown

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

# Markdown

## H2 Heading

Когда я отображаю главную страницу, в заголовке появляется заголовок H2.

У меня есть другие части моего toctree, где я хочу:maxdepth больше 1. Почему sphinx считывает заголовок 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

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

Например, учитывая следующий раздел

Contents  # this will create a <div id="contents>...</>
========

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

В вашем conf.py, внизу добавьте следующие строки

def setup(app):
    app.add_css_file('styles.css')

Теперь в вашей папке _static (которая находится на том же уровне папки, что и ваш conf.py) добавьте файл с именем styles.css со следующими строками

// this selects the contents section, the first table of contents and the list item
// underneath it. Then it removes the spacing to make it look whole. If you have more
// items, you can consider using :not(:last-of-type) selector. 
#contents .toctree-wrapper:first-of-type ul {
    margin-bottom: 0;
}

Answer 3

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

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