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

Question

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

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?

Спасибо!

Answer 1

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

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

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

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

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

Answer 2

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

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

Это опция метаданных для всего файла, подробнее здесь:

http://www.sphinx-doc.org/en/1.4.8/markup/misc.html

Answer 3

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

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

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md

Answer 4

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

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

Answer 5

в моем случае я включил файл readme.MD, но по умолчанию он принимает только файл .md с расширением myst. когда я изменил формат файла, он больше не говорил