Sphinx — в чем разница между toctree и контентом?

Я могу создать оглавление двумя способами:

.. contents::
   :local:
   depth: 1

or as 

.. toctree::
    :maxdepth: 1

    index

В чем разница? Где я должен использовать toctree и где содержимое?


python tableofcontents python-sphinx toctree
person matousc    schedule 29.09.2016    source источник

Ответы (1)


arrow_upward
11
arrow_downward

.. contents — это директива doctutils (основная библиотека который определяет ReST и связанные утилиты) и автоматически создает оглавление из заголовков в текущей теме.

.. toctree — это определяемая Sphinx директива, в которой вы явно указать документы, оглавления которых будут перечислены вне списка.

Например, вы можете использовать .. contents в документе для создания обзора содержимого страницы, например:

===================
Curing World Hunger
===================

.. contents::
   :depth: 1

Abstract
========

…

Problem description
===================

…

Вы бы использовали .. toctree в индексном документе, который практически ничего не содержит:

=================
Scientific papers
=================

Below is a list of papers published here:

.. toctree::
   :maxdepth: 2

   curing_hunger
   …

.. toctree берет список документов для обработки, .. contents нет.

person deceze♦    schedule 29.09.2016