.. highlight:: rst .. _toctree-directive: Содержание (TOC tree) ===================== .. index:: pair: table of; contents Так как reST не имеет возможностей соединять несколько документов друг с другом или разделять документы на несколько различных выходных файлов, Sphinx использует свою собственную директиву для добавления связи между различными файлами, из которых состоит документация, так же как и для создания содержания. Директива ``toctree`` является центральным элементом этого механизма. .. note:: Простое "включение" одного файла в другой может быть сделано при помощи директивы :dudir:`include`. .. rst:directive:: toctree Эта директива вставляет "TOC tree(содержание)" в указанное место при помощи индивидуальных содержаний (включая "подсодержания") докуметов, указанных в теле директивы. Относительные имена документов (не начинающиеся со слеша) рассматриваются относительно документа, в котором находится эта директива; абсолютные имена рассматриваются относительно каталога с исходными файлами. Числовая опция ``maxdepth`` может быть использована для указания глубины дерева. По умолчанию включаются все уровни. [#]_ Рассмотрим такой пример (взят из индекса документации библиотеки Python):: .. toctree:: :maxdepth: 2 intro strings datatypes numeric (ещё много всего) Это означает две вещи: * Добавляются содержания всех этих документов с максимальной глубиной вложения равной 2, что означает один вложенный заголовок. Директивы ``toctree`` в этих документах тоже учитываются. * Sphinx знаетотносительный порядок документов ``intro``, ``strings`` и так далее, и знает что они являются дочерними по отношению к текущему. Исходя из этого он создаёт ссылки "next chapter", "previous chapter" и "parent chapter". **Элементы** Названия документов в :rst:dir:`toctree` будут автоматически прочитаны из заголовков в этих документах. Если это не то, что Вы хотите, Вы можете явно задать название и цель при помощи синтаксиса, похожего на ссылки reST (и Sphinx's :ref:`cross-referencing syntax `). Это выглядит таким образом:: .. toctree:: intro All about 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``, затем все остальные документы (кроме того, который содержит эту директиву, что очевидно.) [#]_ Специальное имя записи ``self`` обозначает документ, содержащий директиву toctree. Это полезно, если Вы хотите создать карту сайта при помощи "sitemap". Кроме того, Вы можете использовать опцию "hidden" :: .. toctree:: :hidden: doc_1 doc_2 В этом случае Sphinx будет в курсе об иерархии докуметов, но ссылки на эти документы не будут добавлены вместо этой директивы. Это полезно если Вы хотите доабвить эти ссылки сами но другим образом. Наконец, все документы в :term:`sphinx source directory` (или подкаталогах) должны быть в какой-либо директиве ``toctree``; Sphinx покажет предупреждение в случае, если он найдёт файл, который не включён в чьё-либо содержание, так как это означает, что этот файл будет не доступен при помощи стандартной навигации. Используйте :confval:`unused_docs` чтобы явно исключить документы из сборки, и :confval:`exclude_trees`, чтобы явно исключить целый каталог. "master document" (определённый в :confval:`master_doc`) - это корневой документ в иерархии содержания. Он может быть исползован в качестве главной страницы документации или как "полное содержание, если не указывать опцию ``maxdepth``. .. versionchanged:: 0.3 Добавлена "globbing" опция. .. versionchanged:: 0.6 Добавлены опции "numbered" и "hidden", так же как и внешние ссылки и поддержка ссылки "self". .. versionchanged:: 1.0 Добавлена "titlesonly" опция. .. versionchanged:: 1.1 Добавлен числовой аргумент для "numbered". Специальные имена ----------------- Sphinx зарезервировал некоторые имена документов для своего использования; Вы не должны создавать документы с такими именами -- это приведёт к проблемам. Эти специальные имена (и документы, создаваемые из них): * ``genindex``, ``modindex``, ``search`` Они используются для создания главного индекса, индекса модуля Python и страницы поиска, соответственно. Главный индекс содержит записи из модулей, всех создающих индексы :ref:`описаний объектов `, и из директив :rst:dir:`index` directives. Индекс модуля Python содержит по записи на директиву :rst:dir:`py:module`. Страница поиска содержит форму, которая испльзует созданный JSON индекс для поиска и JavaScript для полнотекстового поиска по созданным документам; он должен работать на большинстве современных браузеров, которые поддерживают JavaScript. * все имена, начинающиеся с ``_`` Хотя лишь несколько таких имён используется самим Sphinx, Вы не должны создават документы или каталоги с документами с такими именами. (Использование ``_`` в качестве префикса для собственнх каталогов с шаблонами допустимо.) .. rubric:: Footnotes .. [#] Опция ``maxdepth`` не применяется к LaTeX writer, так как у него в начале документа обязательно должно присутствовать полное содержание, и его глубина управляется счётчиком ``tocdepth``, который Вы можете задать в значении настройки :confval:`latex_preamble`:: ``\setcounter{tocdepth}{2}``. .. [#] Примечание по поводу доступного синтаксиса глоббинга: Вы можете использовать стандартные конструкции оболочки ``*``, ``?``, ``[...]`` и ``[!...]`` с учётом того, что они не совпадают со слешами. Двойная звезда ``**`` может быть использована для совпадения с любой последовательностью символов, *включая* слеши.