ВНИМАНИЕ: документ не включен ни в одно дерево для включаемого файла

Получаю предупреждение:

WARNING: document isn't included in any toctree

для файлов, которые существуют в документе, потому что они были явно включены. Итак, у меня есть индексный файл:

.. toctree::
    :maxdepth: 2

   pages/0010-foo
   pages/0020-bar

В файл 0020-bar.rst я специально включаю ряд других файлов, например:

.. contents:: :local:

.. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst

Но когда я создаю проект, я все равно получаю предупреждение о том, что 0070-baz.rst отсутствует ни в одном токтриде, например:

/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree

Странно то, что я вижу содержимое вывода. Это нормально? Всегда ли это предупреждение появляется для файлов, которые явно включены, а не включены через toctree?

Спасибо!


python-sphinx toctree restructuredtext
person NickChase    schedule 06.03.2013    source источник
comment
AFAIK, каждый файл .rst, который явно не включен в токтри, рассматривается Sphinx как случайный, и выдается предупреждающее сообщение. См. Также этот ответ: stackoverflow.com/a/13109215/407651.   -  person mzjn    schedule 07.03.2013

Ответы (4)


arrow_upward
41
arrow_downward

Sphinx будет жаловаться на это независимо от того, включен файл или нет.

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

Поэтому в вашем случае вы можете попробовать изменить conf.py файл Sphinx примерно так:

exclude_patterns = ['pages/reference-architecture', 'some/other/file.txt']

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

РЕДАКТИРОВАТЬ: См .: ответ Джоакима, чтобы узнать о другом варианте, который был добавлен после создания этого ответа.

person Kevin Horn    schedule 15.03.2013

arrow_upward
61
arrow_downward

Если вы хотите только ..include:: документ в другом документе, не отображая его ни в каком toctree.

Добавьте :orphan: в верхнюю часть документа, чтобы избавиться от предупреждения.

Это параметр метаданных для всего файла. Дополнительные сведения см. В документации Sphinx < / а>.

person Joakim    schedule 21.11.2016
comment
Также см. Параметр :hidden: для toctree. - person Josiah; 02.03.2020

arrow_upward
3
arrow_downward

У меня была ситуация, когда я не мог редактировать документы, которые хотел добавить в подмодуль git. У документов уже была собственная структура, включая страницу оглавления, написанную на Markdown, и я действительно хотел, чтобы они обрабатывались sphinx для единообразия форматирования.

Я обнаружил, что могу указать скрытое toctree, чтобы toctree знал о документах, но не загромождал toctree и не добавлял кучу ошибок в мои выходные данные сборки sphinx.

* :doc:`Additional Book <external/index>`

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md
person Josiah    schedule 02.03.2020
comment
Спасибо, в некоторых случаях это кажется хорошим ответом. В нашем случае использовался сгенерированный файл, в который мы не хотели вручную вставлять тег :orphan: вверху. - person Daniel Arndt; 09.07.2020
comment
Мне нравится этот ответ, поскольку он также помогает мне отслеживать, на какие внешние документы есть ссылки в текущем документе. - person panc; 25.05.2021

arrow_upward
2
arrow_downward

Отступы работали:

  toctree::   
   :maxdepth: 2
       hello <h.rst>
       abc <your.rst>
person diveinsky    schedule 21.09.2015
comment
Отступ, который вы показываете, ни в коем случае не требуется, однако пустая строка между :maxdepth: 2 и следующей строкой обязательна. Это также может / должно быть просто h (имя файла минус начало), если нет конкретной причины, по которой вы хотите переопределить заголовок документа. - person pzkpfw; 11.11.2015