ПРЕДУПРЕЖДЕНИЕ: документ не включен в любой файл toctree для включенного файла

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

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?

Благодарю!

Ответ 1

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

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

Так что для вашего случая вы можете попробовать что-то вроде:

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

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

ОБНОВЛЕНИЕ: См.: Joakim answer, чтобы узнать, какая опция была добавлена после создания этого ответа.

Ответ 2

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

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

Это опция метаданных для всего файла. Читайте больше из документации Сфинкса.

Ответ 3

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

  toctree::   
   :maxdepth: 2
       hello <h.rst>
       abc <your.rst>