WARNING: document isn't included in any toctree for included file

I'm getting the warning:

WARNING: document isn't included in any toctree

for files that exist in the document because they've been explicitly included. So I have the index file:

.. toctree::
:maxdepth: 2


pages/0010-foo
pages/0020-bar

In the file 0020-bar.rst, I'm specifically including a number of other files, as in:

.. contents:: :local:


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

But when I build the project, I still get a warning that 0070-baz.rst isn't in any toctree, as in:

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

The weird thing is that I can see the content in the output. Is this normal? Does this warning always appear for files that are explicitly included rather than included via toctree?

54843 次浏览
小开
最佳答案

Sphinx will complain about this whether the file is included or not.

However, you can specifically exclude files by using the exclude_patterns config value.

So for your case you might try to change Sphinx's conf.py file with something like:

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

You can exclude individual files, directories, or use file globbing patterns to match groups of files this way.

EDIT: See: Joakim's answer for another option that was added after this answer was created.

小开

Indentation worked:

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

If you only want to ..include:: a document in another document, without having it appear in any toctree.

Add :orphan: to the top of your document to get rid of the warning.

This is a File-wide metadata option. Read more from the Sphinx documentation.

小开

I had a situation where I couldn't edit the documents I wanted to be brought in as a git submodule. The documents already had their own structure including TOC page written in Markdown and I did want them to be processed by sphinx for consistency of formatting.

What I found I could do is specify a hidden toctree to make toctree aware of the documents, but not clutter up the toctree or add a bunch of errors to my sphinx build output.

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


.. toctree::
:hidden:


external/documentA.md
external/documentB.md

提交答案