Содержание (TOC tree)

Так как reST не имеет возможностей соединять несколько документов друг с другом или разделять документы на несколько различных выходных файлов, Sphinx использует свою собственную директиву для добавления связи между различными файлами, из которых состоит документация, так же как и для создания содержания. Директива toctree является центральным элементом этого механизма.

Note

Простое “включение” одного файла в другой может быть сделано при помощи директивы :dudir:`include`.

.. toctree::

Эта директива вставляет “TOC tree(содержание)” в указанное место при помощи индивидуальных содержаний (включая “подсодержания”) докуметов, указанных в теле директивы. Относительные имена документов (не начинающиеся со слеша) рассматриваются относительно документа, в котором находится эта директива; абсолютные имена рассматриваются относительно каталога с исходными файлами. Числовая опция maxdepth может быть использована для указания глубины дерева. По умолчанию включаются все уровни. [1]

Рассмотрим такой пример (взят из индекса документации библиотеки Python):

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (ещё много всего)

Это означает две вещи:

  • Добавляются содержания всех этих документов с максимальной глубиной вложения равной 2, что означает один вложенный заголовок. Директивы toctree в этих документах тоже учитываются.
  • Sphinx знаетотносительный порядок документов intro, strings и так далее, и знает что они являются дочерними по отношению к текущему. Исходя из этого он создаёт ссылки “next chapter”, “previous chapter” и “parent chapter”.

Элементы

Названия документов в toctree будут автоматически прочитаны из заголовков в этих документах. Если это не то, что Вы хотите, Вы можете явно задать название и цель при помощи синтаксиса, похожего на ссылки reST (и Sphinx’s cross-referencing syntax). Это выглядит таким образом:

.. toctree::

   intro
   All about strings <strings>
   datatypes

Вторая строка содержит ссылку на документ strings, но для заголовка будет использована строка “All about strings” вместо заголовка, опрделённого в документе strings.

Кроме того, Вы можете добавлять внешние ссылки, указывая HTTP URL вместо имени документа.

Нумерация разделов

Если Вы хотите, чтобы ваши разделы были пронумерваны в итоговом HTML, используйте опцию numbered. Например:

.. toctree::
   :numbered:

   foo
   bar

Нумерация начинается с заголовка foo. Подзаголовки тоже будут автоматически пронумерованы (для них не нужно указывать флаг numbered).

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

Дополнительные опции

Если Вы хотите получить только названия документов без других заголовков этого же уровня, Вы можете использовать опцию:

.. toctree::
   :titlesonly:

   foo
   bar

Вы можете использовать “globbing”, при помощи опции glob. В таком случае все записи сравниваются со списоком доступных документов и совпавшие документы затем добавляются в список в алфавитном порядке. Например:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

В этом случае сперва будут добавлены все документы, чьи имена начинаются с intro, затем все документы из каталога recipe, затем все остальные документы (кроме того, который содержит эту директиву, что очевидно.) [2]

Специальное имя записи self обозначает документ, содержащий директиву toctree. Это полезно, если Вы хотите создать карту сайта при помощи “sitemap”.

Кроме того, Вы можете использовать опцию “hidden”

.. toctree::
   :hidden:

   doc_1
   doc_2

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

Наконец, все документы в sphinx source directory (или подкаталогах) должны быть в какой-либо директиве toctree; Sphinx покажет предупреждение в случае, если он найдёт файл, который не включён в чьё-либо содержание, так как это означает, что этот файл будет не доступен при помощи стандартной навигации. Используйте :confval:`unused_docs` чтобы явно исключить документы из сборки, и :confval:`exclude_trees`, чтобы явно исключить целый каталог.

“master document” (определённый в :confval:`master_doc`) - это корневой документ в иерархии содержания. Он может быть исползован в качестве главной страницы документации или как “полное содержание, если не указывать опцию maxdepth.

Changed in version 0.3: Добавлена “globbing” опция.

Changed in version 0.6: Добавлены опции “numbered” и “hidden”, так же как и внешние ссылки и поддержка ссылки “self”.

Changed in version 1.0: Добавлена “titlesonly” опция.

Changed in version 1.1: Добавлен числовой аргумент для “numbered”.

Специальные имена

Sphinx зарезервировал некоторые имена документов для своего использования; Вы не должны создавать документы с такими именами – это приведёт к проблемам.

Эти специальные имена (и документы, создаваемые из них):

  • genindex, modindex, search

    Они используются для создания главного индекса, индекса модуля Python и страницы поиска, соответственно.

    Главный индекс содержит записи из модулей, всех создающих индексы описаний объектов, и из директив index directives.

    Индекс модуля Python содержит по записи на директиву py:module.

    Страница поиска содержит форму, которая испльзует созданный JSON индекс для поиска и JavaScript для полнотекстового поиска по созданным документам; он должен работать на большинстве современных браузеров, которые поддерживают JavaScript.

  • все имена, начинающиеся с _

    Хотя лишь несколько таких имён используется самим Sphinx, Вы не должны создават документы или каталоги с документами с такими именами. (Использование _ в качестве префикса для собственнх каталогов с шаблонами допустимо.)

Footnotes

[1]Опция maxdepth не применяется к LaTeX writer, так как у него в начале документа обязательно должно присутствовать полное содержание, и его глубина управляется счётчиком tocdepth, который Вы можете задать в значении настройки :confval:`latex_preamble`:: \setcounter{tocdepth}{2}.
[2]Примечание по поводу доступного синтаксиса глоббинга: Вы можете использовать стандартные конструкции оболочки *, ?, [...] и [!...] с учётом того, что они не совпадают со слешами. Двойная звезда ** может быть использована для совпадения с любой последовательностью символов, включая слеши.